teamcraft:plan-and-implement-issue

What this skill does

## Why This Skill Exists

Every project has decisions the team spent real time making — how they test, how they branch, what patterns they follow, what architectural boundaries exist, what the product is supposed to do. Those decisions are captured in the project for a reason. A plan that ignores them wastes the developer's time catching mistakes that shouldn't have been made.

Before planning, direct Claude to consult the relevant captured knowledge. Not by reading everything — by reading only what's relevant to the work. That's the whole point of keeping knowledge on-demand instead of always-loaded.

## What to Do

Six steps, in order. Each one must complete before the next begins. Steps 1–2 are read-only and involve zero file modifications. Steps 3+ happen on the work branch only — never on the default branch.

**1. Understand what to build (read-only).** `$ARGUMENTS` is a work item ID, a description of work, or empty. If it matches a file in `.teamcraft/work/`, read that work item. If it's a description, interview briefly — what are we building, why, and what does "done" look like? If empty, ask.

After reading the work item, if it traces back to a documented product requirement, consult the relevant sections of the captured product requirements for acceptance context. Not the whole document — just the relevant sections. This helps you understand the "why" behind the work item.

Do a quick readiness check: are the requirements clear enough to plan? If the acceptance criteria are vague, dependencies are unresolved, or something doesn't add up — surface those gaps now and let the developer decide whether to proceed or clarify first.

**This step modifies nothing. No files change. No commits happen. Branch setup comes next.**

**2. Establish the work branch — before any file modifications.** Do not modify any work item files, INDEX.md, or anything else until you're on the correct branch.

Derive the expected branch name. Follow the team's captured branching convention if one exists. If none is documented, default to `feat/<slug>`, `fix/<slug>`, or `chore/<slug>` based on the work type, with the work item ID in the slug if one exists.

Check whether a branch with that name already exists (local or remote). Three cases:

- **Doesn't exist:** create it from the default branch and check it out. Proceed.
- **Exists with substantive commits on it:** ask the developer, in two sentences: "A `<branch-name>` branch already exists with [N] commits. Do you want to resume work on that branch, or start fresh with a different branch name?" Do NOT offer rebase analysis, divergence strategies, or review of existing commits — that's out of scope for this skill. If they resume: check it out. If they want a different name: ask for one, create that branch instead.
- **Exists with no commits beyond the base / looks stale:** ask whether to reuse or recreate. If recreate, delete the old branch first.

**Never let this skill modify files on the default branch.** After this step, verify you're on the work branch. If for any reason you end up still on the default branch, stop and tell the developer — don't proceed.

**3. Capture or update the work item — on the work branch.** You're now on the correct branch. File modifications are safe.

- **Work item already exists** (it was created earlier via `create-issue`, or exists from a prior session): update its frontmatter to `status: in-progress` and `started: YYYY-MM-DD`. Update the matching row in `.teamcraft/work/INDEX.md`. Commit both with the work item ID in the message.
- **No work item exists yet:** create it now, to the **work-item standard** (`../references/work-item-standard.md`) — draft it from the description of what's being built, confirm acceptance criteria and priority with the developer, then write `.teamcraft/work/<id>.md`, update INDEX.md, and commit — all on this work branch (that's where we are now). Don't hand this off for the developer to run as a separate step. Then update the frontmatter to `status: in-progress` and `started: YYYY-MM-DD`, update INDEX.md accordingly, and commit a second time to record the status transition.

Two separate commits — "work item created" and "work item started" — reads naturally in the branch history and keeps each transition atomic. The work item ID and acceptance criteria must be carried forward through the rest of this skill.

**4. Research current technology docs.** Identify the technologies this work touches and use Context7 to pull current documentation. Plans built against stale APIs produce bugs nobody catches until runtime.

**5. Consult the project's captured knowledge.** Before entering plan mode, consult the four categories of captured project knowledge that commonly apply. For each one, read the INDEX or table of contents first, then drill into only the sections relevant to this work:

- **Team operating conventions** — for anything affecting how you'll do the work (branching pattern, testing approach, commit format, coverage requirements, pre-push expectations, merge strategy). Claude defaults to its training-data priors without explicit guidance — the conventions tell you where the team deviates.
- **System architecture** — for the components this work touches. Where does this code fit in the system? What boundaries does it need to respect? What's the intended direction if the architecture is mid-migration?
- **Technology decisions** — for the areas involved, *and* for any cross-cutting decision that constrains how the work is done even when it isn't *about* this work. Skim every one-line summary in the decisions INDEX and ask two questions of each, not one: "does this decision share a topic with the work?" *and* "does this decision constrain how I should design the work — sequencing, transferability, scope — even if the work isn't about it?" Topic-match alone misses the second kind. If touching persistence, consult the database decision; if touching auth, consult the auth decision. And if this work is one of a sequence — first/middle/last across apps, services, or migrations — consult the convergence/migration/phasing decision, because where a piece sits in a sequence usually dictates how it must be built (transferable as configuration, say, rather than baked to one app). Read only what applies.
- **Product requirements** — for acceptance context when the work item derives from a documented requirement. Confirm your understanding of what "done" looks like aligns with the PRD.

**Consultation discipline:** read the INDEX/TOC first. Drill into specific sections only when they're relevant. Do not read whole documents — that defeats the point of keeping knowledge on-demand. If the team has opted out of the opinionated default structure, locate the documents by reading the repo's README or browsing the standard documentation locations.

**Verify before you trust it.** Locating a doc isn't the same as trusting it — in inherited or brownfield repos, an authoritative-looking doc may be stale legacy content no one verified. After locating a relevant doc, check its Teamcraft certification per `../references/doc-provenance.md`: if it carries a valid `teamcraft` stamp, note its `kind` and `date` and flag possible staleness if the date is old relative to recent work in this area; if a relevant doc lacks the stamp, treat it as UNVERIFIED — surface it and offer to run the matching capture skill to review and certify it. Don't silently trust an unverified doc, and don't refuse to proceed because of one — the developer decides.

After consulting, report what you found that's relevant: conventions that apply, architectural boundaries in play, technology decisions that constrain your choices, requirements sections that shape acceptance. Surface this before plan mode so the plan reflects it — plan mode can deprioritize project context in favor of its own planning instructions.

**Plan for the Definition of Done.** The plan must include the work the change implies beyond the feat