| name | spec |
| description | Produce a verified spec — problem, desired outcome, and acceptance criteria — before building. Use when given a GitHub/Linear issue link, when starting from a fuzzy in-conversation idea, or asked to "figure out what to do" / "scope this" / "what should I build" — whenever the *what* isn't yet pinned down. Grills the ambiguities, checks the premise against the code, and produces acceptance criteria you sign off on — then hands to design-first. |
Settle what to build and why — with verifiable acceptance criteria — before any design or code. This is the front of the pipeline: spec (what) → design-first (how) → code-guidelines + test-guidelines (build) → review (which verifies the result against this spec).
Run it for a tracked issue or a fuzzy ask. Skip it — and say so — when the ask is already a precise, verifiable instruction.
1. Establish the source
Get the raw intent from wherever it lives:
- From a tracked issue (a GitHub/Linear link) — fetch it, don't work from the link text or your memory of it:
- GitHub:
gh issue view <url-or-number> --json title,body,comments,labels,state, plus any linked PRs.
- Linear: the Linear tools — the issue and its comments.
- Read the full body, every comment, labels, and linked issues/PRs. The real decision is often buried in a comment, not the title.
- From an in-conversation idea — start from what the user said, in their words. If a tracked issue might already exist for it, ask for the link; otherwise proceed — the spec itself is the source of truth.
Either way you now hold the raw intent — which is usually vague wherever it came from. Sharpen it in the steps below.
2. Reconstruct the real intent
The raw ask usually names a symptom; the real need is underneath. State, in the domain's own words: the problem this solves, who it's for, and what "done" looks like. Separate the reported symptom from the underlying need — they're often not the same fix.
3. Check the premise against the code
The ask — especially from a tracked issue — may be stale, partial, or simply wrong. Investigate before believing it:
- Does the described behavior actually exist / reproduce? For a bug, find the code path — and if it's non-trivial, build the repro loop now (see diagnosing-bugs).
- Is part of it already implemented, or made moot by a later change?
- Does the codebase contradict the issue's assumptions?
Surface any contradiction to the user before going further — a spec built on a false premise wastes the whole pipeline.
4. Grill the gaps
Interview relentlessly until the intent is unambiguous. One question at a time, waiting for the answer before the next — batching questions is bewildering. Give your recommended answer with each question. If a question can be answered by reading the code, read it instead of asking. Drive out scope, edge cases, and the in-vs-out boundary.
5. Write the spec and get sign-off
Produce, in the conversation:
- Problem — what's wrong or missing, and why it matters.
- Outcome — the desired end state, in the domain's words.
- Acceptance criteria — verifiable, observable conditions (e.g. "capturing an event with X attaches Y"; "the N+1 is gone — one query"). This is the bar
review's Spec axis will check against.
- Non-goals — what's explicitly out of scope.
- Open questions — anything still unresolved.
Done when the user signs off on the acceptance criteria — explicit agreement that meeting them means the work is complete. Not "looks reasonable"; agreement on the bar.
6. Hand off
The what is now settled. This spec becomes the PR description's problem / outcome / acceptance at ship time (pr-writer formats it; review's Spec axis verifies against it). Hand off to design-first to shape the how.
