Plan Draft

/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 line — a reviewer can only annotate what is stated specifically. Where an existing pattern should be followed, point at it by name (e.g. "mirror ExistingValidator") so the implementer copies the canonical shape.
• If any part of the spec is ambiguous, flag it as NEEDS_DECISION with options. Do NOT ask the user directly from within a sub-agent — surface ambiguities in the plan so the main agent can relay them.
• Respect existing ADRs. If your plan contradicts a past decision, flag it explicitly and explain why the decision should be reconsidered.
• Sections that genuinely do not apply may be marked "None" (Out of Scope, Environment & Preconditions, NEEDS_DECISION) — but do not drop them; "None" tells the reader you considered them.

Plan Template

# Implementation Plan: [Feature Name]

## Approval Summary
**Goal:** [1–2 sentences — what the user gains]

**Acceptance Criteria** — each user-visible and testable (`<slug>` = current
git branch name with a redundant leading type prefix like `feat-`/`fix-`/
`worktree-` stripped, `/` replaced by `-`, truncated to 30 chars):
- AC-<slug>-1: [one line: given/when/then]
- AC-<slug>-2: [...]

**Key decisions:** [2–3 bullets, one line each]

**Risk flags:** security surface: [yes/no] · new persisted field: [yes/no] ·
sensitive-category data: [yes/no] · schema migration: [yes/no] ·
new dependency: [yes/no] · new/changed route: [yes/no]

**NEEDS_DECISION:** [one line each, or "None"]

*(The summary above is what the developer approves; everything below is the
detailed contract it stands on.)*

## Source
[User prompt summary / external doc title + URL]

## Context & Decisions
[Why this change exists and the shape of the solution, in a few sentences. Then:
decisions taken during planning, and alternatives considered and rejected — each
with its reason.]

## Requirements
[Complete feature requirements — quoted from the source or reproduced verbatim
from the prompt. Do not summarize.]

## Contract  _(full-stack slices; "None" for pure backend/infra work)_
- Routes: [METHOD /path — purpose, required authority]
- Form fields / params: [name, type, validation rule]
- Response shape: [full page / fragment + target / redirect (per the
  project's redirect convention, if any)]
- Error rendering: [where errors surface, message keys]
- Schema: [tables/columns added or changed]

## Approach
[Step-by-step implementation strategy. Point at existing patterns to follow by
name where one applies.]

## Files
- NEW    [path]: [what it holds / why]
- EDIT   [path]: [what changes / why]
- DELETE [path]: [why]
- MOVE   [old] → [new]: [why]

## Out of Scope
- [What a reader might expect but this change deliberately excludes]

## Edge Cases  _(`<slug>` = same slug as Acceptance Criteria above)_
- EDGE-<slug>-1: [Edge case]: [handling strategy]
- EDGE-<slug>-2: [...]

## Test Strategy
- [AC-<slug>-1] [test name]: [what it verifies]
- [AC-<slug>-2] [...]
- [EDGE-<slug>-1] [test name]: [what it verifies]

## Environment & Preconditions
[Non-behavioural setup the implementer needs — e.g. "migration edited in place,
reset the local DB first". Behavioural claims belong in Test Strategy. "None" if
nothing applies.]

## NEEDS_DECISION
- [Ambiguity]: [options available]

## Risks
- [Anything that could go wrong or needs extra attention]

Output

Return the plan as markdown text. Do NOT write any files — the main agent will submit the plan for review.

Do NOT write implementation code. Output only the plan.