Spec interview

Idea: $ARGUMENTS

Goal: an Approved spec at docs/specs/NNN-<slug>.md that a fresh session can implement without this conversation. Do not write implementation code in this workflow.

1. Ground truth first

• Read the project's CLAUDE.md and any existing docs/specs/.
• Check what is actually installed: runtimes, build tools, Docker. Check the current versions of any framework the user names. Verify these facts; don't recall them.
• When something needed is missing or unusual, say so now and note it for the spec's first milestone.

2. Interview

• Use AskUserQuestion: at most 4 questions per round, usually 2–3 rounds.
• Ask only about decisions that change the design: scope, data model, external dependencies, persistence and auth, stack.
• Don't ask about things that have a conventional default. Record those defaults in the spec instead.
• Put the recommended option first, labelled "(Recommended)", with its trade-off in the description.
• Dig into the hard parts the user may not have considered: money and rounding, ordering, concurrency, edge cases, failure modes.

3. Write the spec

• Start from spec-template.md and fill in every section.
• Include worked examples with exact expected outputs.
  • Compute them with a script, never by hand.
  • They become the canonical test fixtures for unit tests and end-to-end tests.
• Every rule must be testable.
• Milestones: about 8 steps or fewer each. For UI projects: a foundation milestone (styling, components, lint rules, API client, app shell, shared test helpers), then 1–2 screens per milestone.
• Any choice you made on the user's behalf goes under Open questions, not silently into the spec.
• Status: Draft rev 1.

4. Annotation rounds

Ask the user to annotate the file directly: > NOTE: lines anywhere, and answers under the open questions. Then, every round:

1. Re-read the whole file. It has changed on disk.
2. Apply every note, then remove the resolved notes.
3. Move answered questions into the Decisions log, with the rationale.
4. When an answer changes a rule:
   • recompute the affected fixtures with a script;
   • add a fixture that pins the new rule if none does.
5. Review the spec yourself as well, and report any bugs you find in your own earlier drafts.
6. Ask about genuine ambiguities in the user's notes instead of guessing.
7. Bump the revision and add a Changelog entry. In chat, summarize the changes and list everything you decided on the user's behalf.

Repeat until no notes and no open questions remain.

5. Design (projects with a UI only)

Skip this for backend-only and CLI projects. The design is a requirements tool: approve it here, with the spec, so every milestone builds on settled screens and the API is shaped by what those screens need.

The designer needs an interactive Herdr pane. Without Herdr, do these steps yourself in this session.

1. Brief. Once the annotation rounds have settled scope, write docs/design/brief.md from the spec:

   • the screens, and each one's states (loading, empty, error, validation);
   • the widths to support;
   • the data to show, taken from the worked examples;
   • the stack (default: React + Tailwind + shadcn/ui), and the visual direction. Ask the user about direction, and whether they have a design system to build on.

   The user approves the brief.

2. Design. Launch the designer (per the delegation rule) in the project checkout. The project may have no commits yet, so tell the designer to work in the checkout, write only under docs/design/, and not commit. The user reviews directly, with comments on the artifacts or in the designer's pane, until they approve. Track progress through the designer's report.

3. Reconcile the spec with the design. After the design is approved and handed off:

   • fill in the spec's UI and design section, listing each screen with its states and the API data it needs (endpoint and fields);
   • add any states, data or scope changes the design revealed;
   • reconcile the designer's UI contract (docs/design/contract.md: names and roles, copy with plural rules, formulas for computed values, routes, what's visible at each width, focus behavior, timings) with the spec. Every gap becomes a question for the user now, not a guess during the build;
   • check the handoff is complete: tokens.css, the artboards, a PNG per artboard in screens/png/ (artboard HTML doesn't render on its own), contract.md, and a README.md covering every screen and state, with nothing older than the last design change.

   Treat this as an annotation round: bump the revision and add a Changelog entry.

6. Approve

Only when the user explicitly approves the spec (and, for UI projects, the design):

• Set Status: Approved (rev N, <date>).
• Commit the spec, docs/design/ for UI projects, and .gitignore if it is new. Commit nothing else.
• main is branch-only after the initial commit (a hook enforces it). In a repository with no commits yet, this approval is the one commit allowed directly on main. For a later spec revision, commit on spec/rev<N> and merge it with the user's approval.

7. Hand off

Recommend starting the first milestone in a fresh session with /dev-workflow:milestone M0, running as the dev-workflow:architect agent (the project default, or claude --agent dev-workflow:architect). Don't start it in this session; its context is full of interview history.