spec

Separate deciding WHAT to build from building it. Interview the user, ground the answers in the actual codebase, then write a self-contained `SPEC.md` a fresh session can execute without you in the room. `$ARGUMENTS` is an optional starting description. Run this in a session that already has the repo open, so the questions are informed by real code. ## Step 1: Explore enough to ask good questions Skim the codebase for what the feature will touch: the relevant modules, existing patterns to match, the test setup, and any similar feature to model after. Read only — you're gathering context to interview well, not building. ## Step 2: Interview with AskUserQuestion Ask only what you can't answer from the code, in focused rounds (use AskUserQuestion; batch related questions). Cover: - **Scope & outcome** — what does "done" look like from the user's side, and what's the smallest version worth shipping? - **Behavior** — the happy path, then the edge cases (empty, error, concurrent, permission-denied) that actually matter here. - **Boundaries** — what is explicitly OUT of scope for this iteration. - **Constraints** — compatibility, performance, data/migration concerns, security-sensitive surfaces. - **Verification** — how will we confirm it works end to end (a command, a test, an observable behavior)? Where the code implies an answer, propose it as the default in the question rather than asking cold. ## Step 3: Write SPEC.md Write `SPEC.md` at the project root (NOT in `.claude/`). Make it self-contained — a fresh session with no memory of this conversation should be able to execute it: ```markdown # Spec: <feature> ## Goal <what and why, 2-3 sentences> ## Scope - In: <what this iteration delivers> - Out: <explicitly deferred> ## Behavior - <happy path> - <edge cases and how each should behave> ## Touch points - <exact files / modules / interfaces involved, as file:path — named, not vague> ## Constraints - <compat, performance, security, data/migration> ## Verification - <the exact end-to-end check: command to run, test to pass, or behavior to observe> ## Open questions - <anything still undecided — none is ideal> ``` Show the draft and confirm before writing. Then tell the user to run the implementation in a fresh session (`/clear` first) so it starts with a clean context and the spec as its brief. ## Rules - Interview before writing — do not skip Step 2 and guess the spec. - Name real files and interfaces from the codebase; a spec full of placeholders isn't self-contained. - Every spec states its verification step. If you can't name one, say so and ask the user how they'll check. - One feature per spec. If the idea is really three features, say so and spec the one that was asked.