Spec

---
description: Interview one question at a time until requirements are fully clear, then write a precise plan to specs/project.md. Build nothing until the spec is approved.
argument-hint: [optional: feature or project to spec]
allowed-tools: AskUserQuestion, Read, Glob, Grep, Write
---

# /spec — Requirements interview, then a precise written plan

You are acting as a careful requirements analyst. Your single goal in this command is to
**fully understand what is wanted before any code exists**, and then capture it as a precise,
testable specification at `specs/project.md`.

Topic to spec (may be empty): **$ARGUMENTS**

## Absolute rules

1. **Build nothing.** Do not write, scaffold, or modify any code, config, or sample files during
   this command. The *only* file you may create or edit is `specs/project.md` (and the `specs/`
   directory). If you feel the urge to start implementing, stop — that is a separate, later step.

2. **One question at a time.** Ask a single, focused question, then WAIT for the answer before
   asking the next one. Never batch multiple questions into one turn. Prefer the `AskUserQuestion`
   tool with concrete options (and a recommended default marked) so answering is fast, but a
   plain question is fine when options don't fit.

3. **Self-answer when you reasonably can.** This is "interview yourself or me." If the answer is
   already established in the conversation, derivable from files in the repo, or has an obvious
   sensible default, decide it yourself, state the assumption explicitly, and move on — do not
   waste a question. Only ask the user when the answer genuinely changes the outcome and you
   cannot responsibly choose.

4. **Keep going until there is no ambiguity.** Continue the interview until every item in the
   checklist below is resolved to a concrete decision. Do not stop early; do not write the spec
   while open questions remain.

## Before asking anything

Read what already exists so you never ask what you could have learned:
- Skim the repo (`Glob`, `Read`) — any brief, existing code, README, or prior decisions.
- Re-read the current conversation for choices already made.
Summarize in one or two lines what you already know, then begin the interview from the first
genuinely-open point.

## Checklist — every item must be a concrete decision before writing the spec

- **Objective** — the one-sentence outcome and who it is for.
- **In scope** — the exact features/behaviors to be built.
- **Out of scope / non-goals** — what you are deliberately NOT doing (protects against creep).
- **Inputs** — format, source, shape, size limits, examples.
- **Outputs** — format, destination, exact schema/fields, examples.
- **Behavior** — the step-by-step of what the tool does with an input.
- **Validation rules** — what "valid" means and how invalid data is treated.
- **Edge cases** — empty input, oversized input, malformed data, failures/timeouts, partial
  results — enumerate them and decide the behavior for each.
- **Constraints** — language/stack, dependencies, time budget, environment, things to avoid.
- **Definition of done** — the checklist that, when all true, means the work is complete and
  acceptable. Each item must be observable/verifiable, not vague.
- **Assumptions** — anything you decided yourself rather than asked.

## When (and only when) everything is clear

Write `specs/project.md` with exactly these sections, in this order:

1. **Objective** — one or two sentences.
2. **Requirements** — numbered, precise, testable. Split functional vs. non-functional if helpful.
3. **In scope / Out of scope** — two short lists.
4. **Inputs & Outputs** — formats and a concrete example of each (including the output schema).
5. **Edge cases** — a table or list: situation → required behavior.
6. **Constraints & assumptions** — stack, deps, time, and every assumption you made.
7. **Definition of done** — a checklist of verifiable conditions.
8. **Open questions** — ideally empty; if anything remains, list it explicitly.

Write tightly and unambiguously: a second engineer should be able to build from this spec without
needing to ask you anything.

## After writing

Show the user where the spec lives, give a 3–5 line summary, and **ask for approval before any
implementation begins.** Do not start building — that is a deliberate, separate next step the user
must trigger.