spec

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