prepare-plan

Prepare Plan

Interview the user into a spec of provable decisions, then write a plan implement-plan can schedule. Stop for approval after each.

Input: $ARGUMENTS

Reads: the ticket and its linked docs, the code, docs/quirks.md, any existing spec or plan for the ticket. Writes: <root>/docs/plans/<plan>/spec.md and plan.md.

Later skills and resumed sessions see only these files, never this chat — whatever they need goes in a file. <plan> is the plan's name: the name or ticket key in the input, else the branch's ticket key (git branch --show-current | grep -oE '[A-Z]+-[0-9]+'), else a short kebab-case name you propose and the user confirms. Announce it once set: /implement-plan and /review-build later in this session use it without arguments. <root> is the main checkout, root="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")", even when this session runs in a linked worktree — every skill finds the folder there and it outlives worktree removal. The folder is never committed: unless already ignored, add docs/plans/ to "$(git rev-parse --git-common-dir)/info/exclude" (review-build refuses untracked files; .gitignore is tracked).

Invariants

• Read the ticket and the code before asking. Never ask what they answer; ask only what would change the plan.
• Ask through AskUserQuestion: up to 4 questions per call whose answers don't depend on each other — a question that reshapes the others goes alone. Each question names its tag and the Found: fact behind it; each has 2–4 concrete options, the recommended one first and labelled (Recommended), with its one-line reason in the description. Free-form answers arrive through the built-in "Other".
• An unanswered question stays open. "Probably", "sure", "we'll see" are not decisions — re-ask with a sharper recommendation and force a yes / no.
• Every decision has a Check: — runnable command, named test, or manual QA: <step>. Every [product] decision also has an Example: with real values, an edge value included. Cannot write them → the decision is too vague; sharpen it.
• Backward compatibility is closed from grep results, never from memory. Every symbol, path, field, route, or env var the plan names cites file:line or was verified during planning. Never guess a name.
• Backward compatible by default. During a rolling deploy old and new code run side by side, and a rollback runs old code over data the new code wrote — both must keep working. Schema and contract changes are additive (expand), readers move next, removals (contract) ship later as a ## Release follow-up. Anything else is a [compat] decision the user approves explicitly, marked (breaking — approved <date>).
• Write to spec.md the moment something is decided, assumed, or asked. Decisions are append-only: a change is a new D<n> marked supersedes D<m>, with the old one struck.
• Approvals live in the spec's **Status:** line. No plan before spec-approved (short lane: one approval for both); no code before plan-approved.
• After a context compaction, re-read the spec and plan — the files are the truth.