/plan-draft

name: plan-draft
description: >
  Planning rules and plan template for drafting implementation plans.
  Invoked as /plan-draft for an ad-hoc planning session, or used by the
  planner sub-agent in the /feature workflow. (Named plan-draft so it does
  not collide with Claude Code's built-in plan-mode /plan command.)

/plan-draft — Implementation Planning

Use this skill to produce a structured implementation plan before writing any code. Can be invoked standalone (`/plan-draft`) or applied by the `planner` sub-agent during the `/feature` workflow.

---

Context Gathering

Before planning, collect all relevant context:

• **External specs**: If the prompt references an external link or doc, fetch

it before planning — the Requirements section must quote the source verbatim.

• **Codebase**: Read any module-specific `AGENTS.md` files in directories likely to

be affected, ADRs in `docs/adr/`, and relevant product docs in `docs/`.

---

Planning Rules

• **The Approval Summary is what the developer approves.** It is read on a

phone, so constrain the units, not the total: goal in 1–2 sentences, one line per acceptance criterion, one line per key decision, one line per NEEDS_DECISION. There is no hard line cap — the per-item limits keep it short. If the acceptance criteria grow past ~10, treat that as a signal the task should be split into smaller slices, not that the summary should be longer. Each acceptance criterion must be user-visible behaviour, not implementation ("a visitor submitting an invalid form sees the error next to the field", not "add a guard clause in the controller"). Number each criterion `AC-<slug>-n`, where `<slug>` is derived from the current git branch name: strip one leading type prefix if present (`worktree-`, `feat-`, `feature-`, `fix-`, `bugfix-`, `hotfix-`, `chore-`, or similar — these are redundant, every branch in the suite has one), replace remaining `/` with `-`, and truncate to 30 characters — plain `AC-n` restarts at 1 for every feature and collides with every other feature's `AC-1` once tests live side by side in the same suite, so the slug is what keeps the tag globally unique, greppable, and short. Every `AC-<slug>-n` MUST map to at least one Test Strategy entry tagged `[AC-<slug>-n]`; a criterion with no test is an incomplete plan. Everything below the summary is the detailed contract the summary stands on — the two must never disagree.

• **The Contract section is written before Approach** and is what the

end-to-end tests are coded against. For full-stack slices it pins routes, fields/params, response shapes, error rendering, and schema changes. Deviating from an approved Contract during implementation is a material change requiring re-approval. Mark it "None" for pure backend/infra work.

• **Lead with intent.** The **Context & Decisions** section states, in a few

sentences, what problem this solves and the shape of the solution — then lists every decision taken during planning and every alternative considered and rejected, each with its reason. The plan is self-contained: a reader with no access to the planning conversation must understand what to build and why. Nothing load-bearing may live only in the chat.

• The **Requirements** section MUST capture the complete feature requirements

exactly as specified by the user or the linked spec. Do not summarize or omit details — the `code-critic` cross-checks every requirement and edge case in this section against the committed tests. If they come from a document, quote them; if from the user's prompt, reproduce them in full.

• The **Files** section MUST list every file the change touches, each tagged

`NEW` / `EDIT` / `DELETE` / `MOVE`, with a phrase on what changes and why. It is the implementer's checklist and the reviewer's blast-radius map — a file in the diff but not here is an undiscussed change.

• The **Out of Scope** section MUST state the boundary explicitly: what a reader

might reasonably expect this change to include but it deliberately does not. This is where scope disagreements surface cheaply and what stops the implementer gold-plating. Write "None" only if you mean it.

• List ALL edge cases explicitly in **Edge Cases** — do not assume any can be

skipped. Number each edge case `EDGE-<slug>-n`, reusing the same `<slug>` derived for acceptance criteria (see above) — plain `edge-N` restarts at 1 for every feature and collides with every other feature's `edge-1` once tests live side by side in the same suite. Every `EDGE-<slug>-n` MUST map to at least one Test Strategy entry tagged `[EDGE-<slug>-n]`; an edge case with no test is an incomplete plan.

• Flag any potential single-responsibility concerns in the proposed approach.
• Propose a test strategy that covers the happy path AND every identified edge

case. Tests are the plan's deterministic oracle — every claim the plan makes about user-visible behaviour (error placement, section open/closed state, button enable/disable, post-failure page coherence, persistence-vs-UI consistency) MUST map to a committed end-to-end test that exercises the behaviour and observes the rendered result (per project convention; e.g., Playwright for a web UI). If a UI claim is worth writing down in the plan, it is worth committing as a test.

• Do NOT write a manual "Verification" or "QA checklist" of behavioural steps.

If you catch yourself writing "Try X and confirm Y", convert it into a committed test assertion in the Test Strategy. The one exception is **environmental preconditions** that are not themselves behaviour under test (e.g. "a migration was edited in place, so the local DB must be reset first") — record those under **Environment & Preconditions**, not as verification.

• Prefer concrete, quotable statements over prose blobs: name the files, show

the key data class or signature, number the edge cases. The plan is reviewed line by l