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:

# 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.