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.
