Skills/specify/SKILL.md

---

name: specify description: Use when the design is already settled — a long in-context design discussion, an exhaustive tracker issue, or a ratified design handed over by brainstorm — and a spec must be produced from those sources with review but without an interview. The spec-production core: applies the feature-acceptance criterion, writes the spec under paths.spec_dir, runs the parse and grounding-check gates, takes user sign-off, hands off to planner. Bounces to brainstorm the moment the sources do not resolve a load-bearing design decision. Co-equal third entry path alongside brainstorm and tdd.

specify — spec-production entry path

Violating the letter of these rules is violating the spirit.

Overview

specify is where a settled design becomes an approved spec. It takes given sources — a long in-context design discussion, an exhaustive tracker issue, settled design docs, or a ratified design narrative handed over by brainstorm — and produces the spec the planner consumes: with review, but without an interview.

It is the sole home of the spec-production gates: the feature-acceptance criterion, the write-spec step, the parse-every-block self-review, the grounding-check hard-gate, and the user-review gate. Whichever way design work enters — fresh through brainstorm's discovery, or directly from sources that already resolve the design — it passes through specify to become a spec. specify carries the universal invariant no plan without an approved spec.

specify is the producing half of a deliberate split. brainstorm owns deciding — interview, approaches, ratification. specify owns producing — rendering that decision into the canonical artefact and clearing the gates. The split is the toolchain's deepest discipline applied one level up: tdd → implement and debug → implement split RED from GREEN across two dispatches so the spec stays honest; specify splits deciding from producing so the producing phase reads the decision as a source rather than making it inline.

This skill is not opt-in. Unlike tdd (a profile-gated bypass), specify is a core pipeline node: it is the gate before planner on every design path that is not a bug fix or a test-specifiable feature.

When to Use / Skipping

Triggers:

• The design is settled in the sources and a spec must be written: an exhaustive issue body, a long in-context design discussion, or a ratified design brainstorm just handed over.
• A cycle-scope spec is missing for settled work and one is needed.

Use the named alternative instead for:

• A genuine design fork — the sources do not resolve a load-bearing decision. Use brainstorm (its discovery is what resolves the fork). specify itself bounces here the moment it detects this (see The Iron Law and Step 1.5).
• A test-specifiable feature, on a profile that enables tdd — the RED executable-spec is the spec. Use tdd directly.
• An observed bug — use debug directly (RED-first).
• A tidy iteration — use audit directly.
• A trivial mechanical edit — per the project's CLAUDE.md carve-out.

Skipping a gate is never permitted. The interview is brainstorm's, and its absence here is the whole point — but the production gates (criterion, parse-every-block, grounding-check, user-review) are non-negotiable regardless of how the work entered. "The issue looks exhaustive, skip the grounding-check" is the reactive-deference failure this skill must not reintroduce.

The Iron Law

THE SOURCES MUST RESOLVE EVERY LOAD-BEARING DESIGN DECISION BEFORE THE SPEC IS WRITTEN.
IF WRITING THE SPEC FORCES A CHOICE BETWEEN PLAUSIBLE DESIGNS THE SOURCES DO NOT RESOLVE,
  STOP AND BOUNCE TO brainstorm. DO NOT SILENTLY PICK ONE.
THE PRODUCTION GATES — ACCEPTANCE CRITERION, PARSE-EVERY-BLOCK, GROUNDING-CHECK, USER-REVIEW —
  ARE NON-NEGOTIABLE REGARDLESS OF ENTRY PATH.
NO PLAN, SCAFFOLDING, OR DOWNSTREAM SKILL UNTIL THE SPEC IS APPROVED — BY THE USER, OR
  (ONLY UNDER /boss WITH spec_auto_sign ENABLED) BY THE AUTO-SIGN GATE: ALL OBJECTIVE GATES GREEN
  AND A UNANIMOUS ADVERSARIAL spec-skeptic PANEL. MODEL SELF-CONFIDENCE ALONE IS NEVER APPROVAL.

Every clause is non-negotiable. The precondition gate is what makes the no-interview path legitimate rather than merely convenient: it is the honest fork-check that tdd's "is this test-specifiable?" is for test work.

The Process

Step 1 — Explore / re-ground context

Before producing anything, establish what the sources actually say:

• Direct entry (from sources): read the sources in full — the tracker issue body, the in-context design discussion, any settled design docs. This IS the design input. Then git log -5 --format=full for the current state of the project.
• Chain entry (from brainstorm): the ratified design narrative is already in-context. Re-ground lightly — fresh git log, the files the design touches — rather than re-deriving it.
• If the project has a design ledger under paths.design_ledger, walk to the contracts the work touches. Note any status: aspirational source: its code is a target, not verified fact — track it for the Step-4 parse gate.

Step 1.5 — Precondition gate (bounce-back)

Enumerate the load-bearing design decisions the spec must encode — the choices that, decided differently, would change what ships. For each, ask the honest question:

Do the sources resolve this, or am I about to pick it myself?

If every load-bearing decision is resolved by the sources, proceed to Step 2. If even one is unresolved — the sources leave a genuine fork between plausible designs with real trade-offs — STOP and bounce to brainstorm (see Error handling / The Bounce-Back). Do not silently pick one and bake it into the spec; a guessed design ratified into a spec is harder to dislodge than an open question, and it is exactly the reactive-deference failure the gate exists to prevent.

Genuine doubt about whether the sources resolve a decision is itself the fork signal — it resolves to a bounce, not to a guess.

Step 2 — Apply the project's feature-acceptance criterion

The project's CLAUDE.md declares the criterion a feature must satisfy to ship. Apply it now, prospectively. The typical shape is some combination of:

• the project's intended audience naturally reaches for the feature,
• the feature measurably improves correctness or removes redundancy,
• the feature reintroduces no class of failure the project's core constraint exists to eliminate.

If the project declares no criterion, the default is "the feature solves a real user-facing problem and does not contradict a stated design commitment". The orchestrator applies the criterion; do not delegate it to the user.

The criterion is unjudgeable without concrete code. For any cycle with authoring or consumer surface, the spec MUST contain the actual program / invocation / configuration a user would write — and that example is the criterion's empirical evidence. A prose assertion ("a user naturally reaches for X") with no shown code is the unfalsifiable hand-wave the criterion exists to prevent: write the code the user would write, then judge whether it is what the criterion demands. For an infrastructure cycle with no user surface there is still concrete code: show the code the cycle delivers — frequently a test fixture whose correct behaviour is rejection — plus a minimal, honest slice of the north-star program the infrastructure serves. "No surface so no code to show" is the rationalisation to refuse.

Code lifted from an aspirational source is a hypothesis, not evidence. If the concrete code here is lifted from a design_models file (or any status: aspirational source, per Step 1), it carries no validation by default. Treat it as the spec's most suspect bytes: it must clear the Step-4 parse-every-block gate before PASS.

Step 3 — Write the spec

Path: under paths.spec_dir, with a name per the project's naming.policy (see profile schema). Determine the next slot per the policy.

Structure:

# <Title> — Design Spec

**Date:** YYYY-MM-DD
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude

## Goal
## Architecture
## Concrete code shapes
## Components
## Data flow
## Error handling
## Testing strategy
## Acceptance criteria

## Concrete code shapes is mandatory and leads with the user-facing program: the worked author example for a surface cycle (= the Step-2 empirical evidence), or — for a no-surface infra cycle — the code the cycle delivers (often a must-fail fixture) plus a minimal honest north-star slice. The before → after implementation shape (struct / signature / match-arm) for each load-bearing change follows as an explicitly secondary subsection, never first. Prose may explain code, never replace it. Exact bytes / line-numbers remain the planner's job — the spec owns the shape, shown.

Step 4 — Self-review

Inline checklist (not a subagent dispatch):

1. Placeholder scan: any "TBD", "TODO", incomplete sections, vague requirements? Fix.
2. Internal consistency: sections must not contradict. Architecture must match component descriptions.
3. Scope check: focused enough for one plan, or does it need sub-cycle decomposition?
4. Ambiguity check: could any requirement be read two ways? Pick one and make it explicit.
5. Concrete-code check: does ## Concrete code shapes exist and carry before → after code for every load-bearing change (plus the worked user-facing example for a surface cycle)? A load-bearing change described only in prose is a self-review failure to fix.
6. Parse-every-block gate. Extract every fenced code block and run it through the spec_validation gate defined in docs/profile-schema.md (which owns the parser-invocation protocol, the no-parser skip, the malformed-entry failure, and the no-op when the profile declares no spec_validation). A parse failure is a self-review failure — fix the spec; do not pass unparsed bytes downstream. Paste the parse-trace into the chat: a visible trace attests the gate fired; its absence means it was skipped.

Fix issues inline.

Step 5 — Grounding-check (hard-gate)

Dispatch the read-only grounding-check agent. The agent reads the just-written spec with fresh context, extracts its load-bearing assumptions about current behaviour of the codebase, and for each searches the workspace for a currently-green test that ratifies it.

Dispatch carrier — the fields spec_path and iteration_scope, defined authoritatively under Carrier contract in agents/grounding-check.md (note spec_path is an absolute path). That table is the single source for those fields; it is deliberately not restated here, so the two files cannot drift.

The agent returns PASS / BLOCK / INFRA_ERROR. Interpretation:

Agent status	Orchestrator action
PASS	Proceed to Step 6. The report goes into the chat for the record.
BLOCK	Present the report to the user. User either: (a) accepts discard → execute the failure-mode procedure below; or (b) overrides in free chat ("Test <path>::<name> ratifies that") → log the override note and proceed to Step 6.
INFRA_ERROR	Abort. The spec stays as-is on disk; debug the workspace out-of-band and re-dispatch the agent.

Failure-mode procedure (no-override BLOCK):

1. Delete the just-written spec file from the working tree (rm <spec_path> — a shell delete, NOT git rm; never committed).

2. Open a backlog issue (via the project's issue-tracker create command) pointing forward to a future re-design. Include:

   • Title: one-line identity of the deferred work
   • Label: matching the project's vocabulary (feature / bug / idea; promote to BLOCKER if the unratified mechanism is on a core-functionality path)
   • Body: short description plus two structured lines:
     • depends on: <name of the unratified mechanism>
     • context: <why this is deferred>

   If the deferred work needs its own spec on resumption (multi-iteration, cross-subsystem), file it as a milestone container instead of a single issue.

3. Tell the user the spec was retired and which backlog entry was filed. No commit is needed — the issue tracker is the live store.

After the failure-mode procedure runs, the session ENDS. There is no Step 6, no Step 7. The idea is parked until the dependency ships.

Re-dispatch on any post-PASS edit. The PASS report is bound to the exact bytes of the spec at dispatch time. Any subsequent edit — polish, a user-requested change, a wording tighten — invalidates the PASS report and requires a fresh dispatch of grounding-check before the Step-6 sign-off and commit. Step 5 is the last step that touches the spec file; nothing slips between it and the commit.

Step 6 — User-review gate

The spec sits in the working tree as an unstaged file. Tell the user:

Spec written to <path> (uncommitted). Please review it and let me know if you want changes before we start the implementation plan. The orchestrator will commit it once you approve.

Wait for the user's response. If they request changes, edit the file in place (still uncommitted), re-run Step 4 AND re-dispatch Step 5 (the previous PASS report no longer covers the edited bytes), then return here. Only proceed after approval AND a fresh Step 5 PASS.

The orchestrator commits the approved spec after sign-off (suggested commit subject: spec: <cycle> <topic>). The skill does not perform the commit itself.

In /boss (autonomous): specify is dispatched autonomously — it is bounded (no interview). It runs the criterion, parse, and grounding-check gates without a checkpoint. What happens at this gate then depends on the profile slot pipeline.boss.spec_auto_sign:

• Slot absent or false (default): specify pauses here as a problem-state notify ("spec X ready, please sign off") and waits for the user. This is the final sign-off pause, not a pre-dispatch checkpoint — the distinction from brainstorm, which /boss bounces before dispatch. This is the conservative default; the user's signature is mandatory.

• Slot true: the orchestrator MAY sign in the user's place, but only through the auto-sign gate below. The gate exists because the orchestrator that wrote the spec is the worst-placed party to judge it — so the gate is built to not rely on the orchestrator's own confidence. Run it in two stages:

  1. Objective gates (all must already hold — these are facts, not judgements):

     • Step 1.5 precondition gate passed cleanly — no load-bearing fork was silently picked (if one had been, specify would have bounced, so reaching here is the evidence; do not re-decide it).
     • Step 4 self-review clean, including the placeholder scan (no TBD / TODO / incomplete section) and a pasted parse-trace for every configured-label block.
     • Step 5 grounding-check returned PASS — not an overridden BLOCK. An override needs a human; with no human in the loop a BLOCK can never be overridden, so any non-PASS grounding result denies auto-sign outright.

     If any objective gate is not green, do not run the panel — fall straight to the human sign-off pause (the default-slot behaviour above), carrying the failing gate in the notify.

  2. Adversarial panel (unanimous-or-nothing): dispatch the read-only spec-skeptic agent five times in parallel, once per lens — criterion, grounding, scope-fork, ambiguity, plan-readiness. Carrier per dispatch: spec_path (absolute), iteration_scope, and the single lens. Each juror tries to refute the spec along its lens and returns SOUND / BLOCK / INFRA_ERROR.

     Panel outcome	Orchestrator action
     All five SOUND	Auto-sign. Commit the spec yourself (subject spec: <cycle> <topic> (boss-signed)), send the informational auto-sign notify (see boss § Notifications — names the capability in user terms and states the plan is proceeding and a reply vetoes), then proceed to Step 7. No pause.
     Any BLOCK or INFRA_ERROR	No auto-sign. Fall back to the human sign-off pause; the notify carries which lens(es) blocked and their findings, so the user sees why it routed to them.

  The fall-back is not a failure — it is the panel correctly routing a spec to the human who was going to review it anyway. A unanimous SOUND is the only thing that lets the orchestrator sign; "the spec looks good to me" never is.

  Auto-sign commits on main are forward-only like every other commit. A later user veto is a forward correction (revert / revised spec / git checkout of downstream working-tree work), never a history rewind — same discipline as any other orchestrator call (see boss § Direction freedom).

Step 7 — Hand off to planner

The terminal state of specify is invoking planner. NO other skill is invoked from specify. NO direct jump to implement.

Hand off carries:

• path to the spec under paths.spec_dir
• iteration scope ("the first iteration covers section X+Y of the spec")

The Bounce-Back

specify returns to brainstorm whenever the precondition fails — the sources do not resolve a load-bearing design decision (Step 1.5), or a grounding-check BLOCK reveals an unratified mechanism the user does not override (Step 5 failure-mode routes to a re-design). On a precondition bounce:

1. Nothing was written yet (the gate fires before Step 3), so there is no working-tree artefact to discard.
2. Invoke brainstorm with the unresolved design question as the cycle request. From there the normal brainstorm → specify → planner path runs.

The bounce-back is not a failure of this skill; it is the skill correctly refusing to ratify an un-chosen design into a spec — the same discipline tdd applies when behaviour is not test-specifiable.

Handoff Contract

Direction	Carrier
user / issue (design settled) → specify	the sources: issue body, in-context design discussion, design docs
brainstorm → specify	ratified design narrative (approaches chosen, constraints, sections approved) — in-context; brainstorm writes no spec file
specify → grounding-check (Step 5)	spec_path (absolute) + iteration_scope
specify → spec-skeptic panel (Step 6, /boss + spec_auto_sign only)	spec_path (absolute) + iteration_scope + one lens per dispatch, five in parallel
specify → planner (Step 7, on PASS or overridden BLOCK)	path to spec + iteration scope
specify → brainstorm (precondition bounce)	the unresolved design question as a cycle request; no spec written
specify → issue backlog (Step 5, no-override BLOCK)	new issue naming the unratified dependency; spec file deleted from the working tree

Common Rationalisations

Excuse	Reality
"The issue looks exhaustive — skip the grounding-check / criterion too"	The interview is what specify skips, by design. The production gates are not the interview; they are what keeps the spec honest no matter how it entered. Skipping a gate because the sources look thorough is the exact reactive-deference failure this skill must not reintroduce.
"There's a small open fork but the sources mostly decide it — I'll pick the rest"	"Mostly decided" with one real fork left is an unresolved design, and a guessed design baked into a spec is harder to dislodge than an open question. That is the bounce-back trigger — stop and go to brainstorm.
"Genuine doubt whether the sources resolve this — but bouncing feels like overkill"	Doubt about whether the sources resolve a decision is the fork signal. It resolves to a bounce, not a guess. The bounce is cheap (nothing is written yet); a wrong guess in a ratified spec is not.
"The shape is clear from the prose, I don't need to paste the code"	If it's clear, pasting it is free; if pasting it is hard, it wasn't clear. The acceptance criterion is unjudgeable without the worked code.
"The block obviously parses — I wrote it carefully"	Careful authoring is not a parse. A spec's code blocks are hypotheses until the live tool accepts them. If a parser is configured for the fence label, run it and paste the trace.
"Just polishing a wording after PASS, no need to re-dispatch"	The grounding-check report attests to specific bytes. A polish edit changes the bytes; the attestation no longer covers them. Re-dispatch is cheap.
"It's in a model doc / the design ledger, so it's canonical"	A models / RFC / proposal doc holds aspirational code — a target, not verified fact. Code lifted from a status: aspirational source must clear the Step-4 parse gate like any other block.
"In /boss with auto-sign on, this spec looks solid — I'll sign and move on"	Your sense that it looks solid is the exact signal the auto-sign gate refuses to trust. Signing requires all objective gates green AND a unanimous spec-skeptic panel. If you find yourself wanting to sign on confidence, that is the cue to run the gate, not to skip it.
"One lens blocked on something minor — I'll sign anyway since the rest passed"	The panel is unanimous-or-nothing by design. One BLOCK routes the spec to the human who was going to review it regardless. You do not get to overrule a juror; that is the whole point of replacing your eye with five independent ones.

Red Flags — STOP

• An unresolved design fork silently picked instead of bounced (any flavour)
• "The sources are thorough, skip a gate" thoughts (any flavour)
• A load-bearing change described in prose with no before → after code block; a surface cycle with no worked user-facing example
• A spec carrying a code block whose fence label has a configured spec_validation parser, committed without a parse-trace in the chat
• Lifting code verbatim from a status: aspirational source without flagging it for the Step-4 parse gate
• Editing the spec file after a Step 5 PASS without re-dispatching
• (auto-sign) About to sign a spec in the user's place on confidence — without all objective gates green AND a unanimous spec-skeptic panel; or overruling a single juror's BLOCK
• (auto-sign) Running the panel before the objective gates are green, or running it at all when spec_auto_sign is not enabled
• Jumping straight from spec to implement (must go via planner)
• Running an interview here (that is brainstorm's job — if the work needs one, bounce)

Cross-references

• Output target: ../planner/SKILL.md — only valid next skill.
• Discovery front-end / bounce-back target: ../brainstorm/SKILL.md — produces the ratified design specify consumes on the chain path, and reclaims the work when the sources do not resolve a design fork.
• Sibling fast path: ../tdd/SKILL.md — the same bounce-to-brainstorm-on-fork discipline, for test-specifiable work; its RED executable-spec is the spec, so it skips both specify and planner.
• Agent dispatched: agents/grounding-check.md — dispatched in Step 5 as a hard-gate. Reads the spec with fresh context and reports PASS / BLOCK / INFRA_ERROR.
• Agent dispatched (auto-sign only): agents/spec-skeptic.md — dispatched in Step 6 five times in parallel (one per lens) ONLY under a /boss session with pipeline.boss.spec_auto_sign enabled. Each juror tries to refute the spec along its lens; a unanimous SOUND is what lets the orchestrator sign in the user's place. Any BLOCK falls back to the human sign-off pause.
• Ad-hoc dispatch. The orchestrator MAY also ad-hoc dispatch ../planner/agents/plan-recon.md during Step 1 when the work enters code territory not recently read; opt-in, not part of the standard process.
• Project feature-acceptance criterion: declared in the project's CLAUDE.md. Applied prospectively in Step 2.