teamcraft:improve-teamcraft

What this skill does

## Why This Skill Exists

Teamcraft only improves if real friction gets back to the people who maintain it — and gets back in a form they can act on. A vague "the planning skill felt off" costs more than it's worth: someone has to reconstruct what happened, guess the cause, and decide if it's even real. A report that names the skill, quotes the line that misled the agent, says what was ruled out, and proposes a fix can be triaged in a minute.

This skill's job is to turn the first kind of feedback into the second. The hard, valuable part isn't writing the issue — it's **vetting**: deciding whether what frustrated the user is actually a defect in a Teamcraft skill, or something else wearing that costume (the user's own project setup, the harness, the model having a bad moment, or the skill being misused). Filing noise upstream is worse than filing nothing.

So the centre of gravity here is honest triage grounded in the skill's *actual* source — not transcribing a complaint, and not rubber-stamping the user's diagnosis.

## The One Non-Negotiable: Ground the Verdict in the Real Skill Text

Before you form any opinion about cause, **open the implicated skill's `SKILL.md` and read the part that supposedly misbehaved.** The skills being critiqued ship in the same installed `teamcraft` plugin as this one — they're siblings. Read them. Quote them.

This is what separates a useful report from a plausible-sounding wrong one. The best feedback Teamcraft has ever received did exactly this: it read the skill, quoted the offending bullet, and showed how that specific wording produced the bad outcome. You cannot root-cause a skill you haven't read.

**Where it showed up is not always where it came from.** Feedback isn't really "about a skill" — it's about a point in the user's workflow where something went wrong or could be better. Hold three things apart:

- **Manifestation locus** — the skill they were running when they noticed it.
- **Cause locus** — where the root cause actually lives. It may be that same skill, an *upstream* skill that ran earlier, or *neither*.
- **The seam** — Teamcraft skills don't call each other; they coordinate through world state (the work item, INDEX, the branch, the captured docs). So a cross-skill bug is usually a **contract bug at the handoff**: one skill left the artifact or state in a shape the next didn't expect, or didn't leave something the next needed. The bug is in neither skill's body — it's in the seam.

So when more than one skill is on the path, reading one `SKILL.md` isn't enough: **read every skill the work passed through, and the artifact/state each handed to the next.** Otherwise you'll "fix" the skill where it surfaced and miss the one that caused it. "I'm not sure which skill" is a perfectly good starting point — it means *investigate the path*, not *make the user pick*.

The reference examples may closely resemble the case in front of you — that's calibration, not a shortcut. **Re-derive every verdict from the live source anyway; never transcribe an example's root cause.** An example can be wrong, or right about a different version of the skill than the one installed now.

## What to Do

Six beats. They're a methodology, not a rigid script — adapt to what the user brings. But don't skip the vetting, and don't skip grounding it in the source.

**1. Understand the intent.** `$ARGUMENTS` is what went wrong, an improvement idea, or empty. People arrive three ways, all handled the same:
- *"This just happened"* — the failure is in the current session. That live context is your best evidence; use it.
- *"This keeps annoying me"* — a recurring pattern they're recounting from memory. Interview for a concrete instance.
- *"I have an idea"* — a pure improvement with no failure attached. Legitimate; it routes to a feature-request rather than a bug.

Establish what the user expected and what actually happened. Establish *where it showed up* — but don't force a single skill out of them. They may name one skill, several, "the build loop," or "validate-issue, but I think it's really upstream in plan-and-implement — or the combination, I'm not sure." All of those are valid; the last is often the most useful, because the seam between skills is where the subtle bugs live. Don't presuppose they hit a defect, and don't presuppose it's confined to one skill — you don't know either yet.

**2. Gather evidence.** Read the implicated skill's `SKILL.md` (and any reference files it leans on) from the installed plugin. When more than one skill is on the path, read each one — and read the artifact or world state each hands to the next (the work item file, INDEX, branch, captured docs), because that handoff is where cross-skill bugs hide. Read the `teamcraft` plugin manifest for the version and the `repository` URL — both feed the issue and neither should be hardcoded or guessed. Reconstruct the concrete failure: what each skill on the path instructed, what the agent did, what state moved between skills, what the user saw, what they expected instead.

**3. Vet — the heart.** Root-cause the symptom against the skill text you just read, and sort it honestly:

- **Bug** — a skill instruction (or a gap in one) led the agent to the wrong outcome. *This is the target.* Example: a relevance heuristic that trains topic-matching and so skips a cross-cutting decision.
- **Feature-request** — Teamcraft works as written but is missing coverage, or the user has an idea that would make it better. Also worth filing.
- **Misuse** — the skill actually handles this; it just wasn't followed (skipped a step, ignored a gate). Not a Teamcraft defect.
- **Harness / environment** — Claude Code itself, an MCP server, the backend tool, or the model's behavior. Not Teamcraft.
- **Project-specific** — the user's own `CLAUDE.md`, repo config, or conventions. Not the plugin.

Actively try to *rule out* the non-Teamcraft causes — and say what you ruled out and why. "Things that are NOT the cause" is one of the most valuable parts of a report; it stops the maintainer re-doing your investigation.

Then settle **scope**, which is orthogonal to type — a bug or a feature-request can be any of these:
- **single-skill** — cause and symptom live in one skill.
- **cross-skill (seam)** — symptom in one skill, cause in another or in the handoff contract between them. Name both loci and describe the seam: which artifact/state crossed it, and how its actual shape differed from what the consuming skill expected.
- **workflow** — the feedback is about how several skills fit together (e.g. "the build loop should be designed differently"), not any one of them. Usually a feature-request; the affected-skills list is the set in that workflow.

Don't collapse a cross-skill or workflow issue into the single skill where it surfaced — that's how the wrong skill gets "fixed" while the real seam stays broken.

**4. Decide whether to file.** Present your verdict plainly, including "I don't think this is a Teamcraft problem — here's what I think actually happened." Then:
- Search existing issues on the repo first (`gh issue list --search`, scoped to the repo from the manifest) — search across both open and closed issues, and try a couple of phrasings (the skill name, and a few words of the symptom), since a near-duplicate rarely shares your exact wording. If something matches, offer to add a comment to that issue instead of opening a duplicate. An empty backlog is a fine result — don't over-search.
- Recommend based on the verdict. **The developer has final say.** If you concluded it isn't a skill issue and they still want it filed, file it — framed honestly as what it is, not dressed up as a defect. This skill never refuses the user; it advises and then does what they decide.

**5. Structure the issue.** Draft it in the shape that `references/example-feedback-issue.md` shows — read that file before drafting so the output is consistent and agent-ingestible. Show the full draft to the developer and