git:20260815.1609140 to git:20260815.efaaa8c

---

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

`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

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.

- 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

<!-- COUPLING NOTE: this template's section names and semantics are consumed

elsewhere — the code-critic skill cross-checks diffs against Approval

Summary / Contract / Requirements / Approach / Edge Cases / Test

Strategy / Files / Out of Scope, and the feature skill presents the

(Step 2), and builds the PR's AC → test table (Step 9). When adding,

renaming, or removing a section, update those consumers in sync. -->

```markdown

# Implementation Plan: [Feature Name]

## Approval Summary

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

**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

1. [Edge case]: [handling strategy]

## Test Strategy

- [edge-N] [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.