Reviewing and approving a spec

You are the gate. This page is what to do when a spec lands in your queue — in the order that catches the most, soonest.

The checklist, in order

1. 1 · Read the requirements and ignore everything else

   Ask one question: if exactly these criteria were satisfied, would the ticket be done? If the answer is no, stop. Nothing below this matters, because the design is a solution to the wrong problem.

2. 2 · Look for the requirement that is missing

   Drafted requirements are usually right about what was said and thin about what was assumed. Error paths, empty states, permissions and migration of existing data are where the gap normally is.

3. 3 · Follow two or three citations

   Click them. You are not auditing all of them — you are testing whether the citations in this spec are real. If two resolve and say what the claim says, the rest probably do too. If one does not, read the whole design differently.

4. 4 · Read every UNVERIFIED claim

   Each one is a decision being handed to you. Answer it, or send the spec back. Approving a spec with an unanswered UNVERIFIED is approving a guess you have agreed to be surprised by.

5. 5 · Check each task is genuinely one pull request

   A task that is really three is where build runs go wrong: the commits stop mapping to reviewable units and the pull request becomes the diff you were trying to avoid reading.

6. 6 · Approve, or ask for v2

   Approval pins your name to this version. A revision is cheap — it is a new version, and v1 keeps its record.

Three failure modes worth naming

The plausible design

Well-written, internally consistent, and grounded in nothing. The tell is citation density: a design section with almost no citations is a design section the agent wrote from general knowledge of software rather than from your software.

The requirement that restates the ticket

"The system shall let the user export the report" is a title, not a criterion. A real criterion says when, in what format, and what happens when it fails.

The rubber stamp

Four specs approved in ninety seconds. This is the exact failure the station exists to prevent, and the only defence is a named owner with time to do it.

What your approval commits you to

• It records you, by name, against this version, with a timestamp — permanently, and append-only.
• It unlocks the build station for this spec and nothing else.
• It is re-checked at the point of use: if the spec is superseded, the build of the old version does not quietly proceed.

The enforcement mechanics are in The human gate.

Reviewing outside the app

The spec is fetchable as markdown once approved, which is useful for reading in an editor or attaching to a ticket:

specd spec pull CRM-131        # markdown, approved specs only
specd spec status CRM-131      # exit 0 approved · exit 3 not approved

Note the direction: the CLI can read an approved spec, and cannot approve one. That refusal is server-side, so it holds regardless of what the binary asks for.