Skills/docs/specs/2026-06-04-specify-entry-path-design.md

specify — Spec-Production Entry Path — Design Spec

Date: 2026-06-04 Status: Draft — awaiting user spec review Authors: orchestrator + Claude

Goal

Add a third entry path into the dev cycle: a specify skill that produces an approved spec from given sources (a long in-context design discussion, an exhaustive tracker issue, settled design docs) — with review, but without an interview.

The driving observation: when the design is already settled, today's brainstorm forces redundant work — it re-opens an interview and re-litigates decisions the sources already made. That is friction, and worse, the re-litigation invites reactive churn on settled calls. But the production half of brainstorm — apply the acceptance criterion, write the spec, parse-gate it, ground-check it, get user sign-off — is wanted in every case. specify is that production half, callable on its own.

The split is the existing toolchain philosophy applied one level up. tdd → implement and debug → implement split a discipline across two dispatches so the spec stays honest (the test is written before any implementation). specify does the same to design work: a deciding phase (brainstorm) and a producing phase (specify), split so the producing phase reads the decision as a source rather than making it inline.

Architecture

Three co-equal entry paths feed one production core. specify is the sole home of the production gates; brainstorm becomes an optional discovery front-end.

brainstorm ──► specify ──► planner ──► implement     design open (discovery + production)
              specify ──► planner ──► implement       design settled in sources
tdd ─────────────────────► implement (mini)           test-specifiable (test = spec)
debug ───────────────────► implement (mini)           bug (RED-first)
   ▲
   └── bounce ── specify / tdd                         unresolved design fork → discovery

The hard-gate moves. Today brainstorm itself is the "no plan without an approved spec" gate. After this cycle, specify carries that invariant (it produces and gets sign-off on the spec, and gates planner); brainstorm is no longer itself a gate — it is the optional discovery stage before specify. The universal invariant — no plan without an approved spec — is unchanged word-for-word; only its carrier moves from brainstorm to specify.

The bounce-back symmetry. specify is a fast path that is only legitimate when its precondition holds — the sources resolve every load-bearing design decision. The moment writing the spec would force a choice between plausible designs the sources do not resolve, it STOPs and bounces to brainstorm. This is structurally identical to tdd's bounce: tdd bounces when one honest assertion cannot pin the behaviour; specify bounces when the sources cannot pin the design. Both fast paths fall back to the same discovery skill.

Discovery vs. production, by verb. brainstorm owns deciding: interview, explore 2–3 approaches, ratify the chosen design with the user. specify owns producing: render the decision into the canonical spec artefact, run all gates, get artefact sign-off. The two reviews are different: brainstorm's per-section ratification asks "is this design right?"; specify's Step-8 review asks "is the written spec faithful and complete?". In the direct path there is no design ratification (no discovery happened) — only the artefact review. That absence is "with review, but without interview".

Concrete code shapes

The canonical authoring form for this prose-skill project is the SKILL.md body and the cross-skill topology. The user-facing artefact the cycle delivers is specify/SKILL.md and the edited dispatch logic in boss.

specify/SKILL.md — the Iron Law (the load-bearing shape)

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 OR CODE WORK UNTIL THE SPEC HAS BEEN PRESENTED AND THE USER HAS APPROVED IT.

specify/SKILL.md — process spine

Step 1   Explore / re-ground context
           - direct entry: read the sources (issue body, in-context
             discussion, design docs) + git log; this IS the design input.
           - chain entry (from brainstorm): the ratified design narrative
             is in-context; re-ground lightly (fresh git log, touched files).
Step 1.5 PRECONDITION GATE
           - enumerate the load-bearing design decisions the spec must encode.
           - for each: do the sources resolve it, or am I about to pick one?
           - any unresolved fork → BOUNCE to brainstorm (see Error handling).
Step 2   Apply the feature-acceptance criterion + write the concrete code
           (the worked user-facing example = the criterion's empirical evidence).
Step 3   Write the spec under paths.spec_dir (mandated structure).
Step 4   Self-review (placeholder / consistency / scope / ambiguity /
           concrete-code / parse-every-block gate).
Step 5   Grounding-check (hard-gate) — dispatch read-only grounding-check.
Step 6   User-review gate — spec sits uncommitted; await approval;
           on change request re-run Step 4 AND re-dispatch Step 5.
Step 7   Hand off to planner (spec path + iteration scope).

specify has no interview step and no approaches step — those are brainstorm's. It dispatches the existing grounding-check agent; it introduces no new agent.

boss — the three-way Entry-path reflection

boss Entry-path reflection (feature work, tdd-enabled profile):

  one honest minimal assertion pins the behaviour   → tdd          [autonomous]
  sources resolve every load-bearing decision        → specify      [autonomous]
  writing one assertion / spec forces an unresolved
    design choice                                     → brainstorm   [bounce-back]

  asymmetry: tdd and specify are bounded (no open Q&A) → dispatch autonomously.
             brainstorm is high-context discovery the orchestrator cannot
             compact on its own → bounce-back before dispatch.
  specify in /boss still pauses internally at its Step-6 user-review gate
    (problem-state notify: "spec X ready, please sign off") — that is the
    final sign-off pause, NOT a pre-dispatch checkpoint.

Implementation shape (secondary — the before → after of each edited file)

brainstorm/SKILL.md
  - Step 6–9 (write spec, self-review, grounding-check, user-review, hand off
    to planner)  ──►  REMOVED (moved to specify).
  - Step 9 terminal "invoke planner"  ──►  "hand ratified design to specify".
  - Hard-Gate block + "spec before plan" framing  ──►  removed / re-pointed:
    brainstorm is no longer itself the gate.
  - Skip rules: brainstorm gains an explicit "optional when design is settled
    in sources — that is specify's direct path" clause.

boss/SKILL.md
  - Entry-path reflection: two-way  ──►  three-way (add the specify branch).
  - Pipeline ASCII block: add specify node on the brainstorm→planner edge.
  - Common Rationalisations / Red Flags: add the "route settled design to
    brainstorm to be safe" anti-pattern (mirror of the existing tdd one).

docs/pipeline.md
  - ASCII graph: brainstorm ─► specify ─► plan; specify ─► plan direct edge;
    specify ─(design fork)─► brainstorm bounce edge.
  - Phase descriptions: new `specify` block; brainstorm block trimmed to discovery.
  - Skip rules: "brainstorm is never skipped at cycle start"  ──►  "specify is
    never skipped at cycle start; brainstorm is the optional discovery stage
    before it, skipped when the design is already settled in the sources".

docs/profile-schema.md, docs/design.md, README.md
  - profile-schema pipeline: gates:[planner] moves brainstorm ──► specify;
    specify documented as a CORE node (not opt-in, unlike tdd).
  - design.md pipeline-form line + README skill table: add specify row,
    flip brainstorm's "Mandatory?" cell to optional-discovery.

tdd/SKILL.md
  - Cross-references: name specify as the sibling fast path with the same
    bounce-to-brainstorm discipline.

Components

• specify/SKILL.md (new). The production core. Follows the skill template: Overview, When to Use / Skipping, the Iron Law (precondition gate + bounce-back + non-negotiable gates), the numbered process spine above, Handoff Contract, Common Rationalisations, Red Flags, Cross-references. Dispatches grounding-check; no new agent.

• brainstorm/SKILL.md (edited). Shrinks to discovery: explore context, interview, 2–3 approaches, per-section design ratification. Terminal state changes from planner to specify. The hard-gate language and the spec-writing / self-review / grounding-check / user-review / planner-handoff steps are removed (they now live in specify). brainstorm no longer writes a spec file; it hands a ratified design narrative to specify in-context.

• boss/SKILL.md (edited). Entry-path reflection becomes three-way. specify direct-entry is autonomously dispatchable (bounded, like tdd/debug), pausing only at its internal user-review gate. The pre-dispatch bounce-back stays reserved for a fresh brainstorm cycle (high-context) and for a surfaced fork.

• tdd/SKILL.md (edited). Cross-references gain specify as the sibling fast path sharing the bounce-to-brainstorm discipline.

• docs/pipeline.md, docs/design.md, README.md, docs/profile-schema.md (edited). Pipeline graph, phase descriptions, skip rules, skill table, and the profile pipeline block updated so all four renderings of the pipeline agree on the three-path shape and on specify as the new production gate.

Data flow

Carrier contracts (the in-context narrative is the carrier where two skills run in the same orchestrator context — no intermediate artefact, exactly as tdd → implement carries the chat history plus the RED-test path):

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 — same carrier brainstorm uses today
specify → planner (Step 7, on PASS or overridden BLOCK)	path to spec + iteration scope
specify → brainstorm (precondition bounce, or no-override BLOCK route)	the unresolved design question as a cycle request
boss Entry-path reflection	dispatches tdd / specify autonomously, or bounces back a fresh brainstorm cycle

Error handling

• Precondition fails (Step 1.5). specify finds, while enumerating the load-bearing decisions, a fork the sources do not resolve. It STOPs before writing the spec and bounces to brainstorm with the design question as a cycle request. The working tree is clean — nothing was written. This is the cheap, early bounce (cheaper than tdd's, which may discard a written test).

• grounding-check BLOCK (Step 5). Identical failure-mode procedure to today's brainstorm: present the report; on no override, delete the just-written spec from the working tree, file a forward backlog issue (or milestone container) naming the unratified dependency, tell the user, end the session.

• grounding-check INFRA_ERROR. Abort; spec stays on disk; debug the workspace out-of-band; re-dispatch.

• Step-6 change request. Edit the spec in place (still uncommitted), re-run Step 4 (self-review) AND re-dispatch Step 5 (grounding-check) — the previous PASS no longer covers the edited bytes — then return to the review gate.

• specify in /boss. Dispatched autonomously; runs criterion, parse-gate, and grounding-check without a checkpoint; pauses at the Step-6 user-review gate as a problem-state notify ("spec X ready, please sign off"). The distinction from brainstorm: no pre-dispatch checkpoint (specify is bounded, no interview), only the final artefact sign-off.

Testing strategy

This is a prose / Markdown skill repo with no executable test suite and (currently) no dev-cycle-profile.yml. "Tests" are internal-consistency properties, verified by audit / architect drift-review at cycle close:

1. No path-count drift. No skill or doc still asserts the two-path model. Every mention of the entry paths names three.
2. Pipeline renderings agree. The pipeline graph in docs/pipeline.md, README.md, docs/design.md, and boss are mutually consistent on the three-path shape and on specify as the production gate.
3. specify/SKILL.md follows the template. Iron Law, numbered process, Handoff Contract, Common Rationalisations, Red Flags, Cross-references all present.
4. No orphaned gate language in brainstorm. No leftover hard-gate / spec-writing / planner-handoff prose; its terminal state names specify.
5. Carrier contracts close. Every specify carrier has a named counterpart skill, and every skill that hands to specify (user, brainstorm, boss reflection) is reflected in specify's own Handoff Contract.

Note on the Step-5 grounding-check during this very cycle. Because this repo has no test suite and no profile, the grounding-check hard-gate is degenerate here — there is nothing green to ratify and the agent is under-configured. The spec's load-bearing assumptions are plain SKILL.md content facts (brainstorm's current terminal is planner; tdd is opt-in; boss has a two-way reflection), read and verified directly during exploration. The agent is therefore not dispatched into the void; this paragraph is the visible trace that the gate was consciously skipped for a degenerate setup, not silently bypassed.

Acceptance criteria

Default criterion (no project CLAUDE.md): solves a real user-facing problem; contradicts no stated design commitment.

• Real problem solved. When the design is settled in the sources, the orchestrator reaches planner through specify with no interview and no re-litigation of settled decisions — while still passing every production gate.
• Anti-deference preserved (the load-bearing one). specify cannot become the lazy "sources look exhaustive, skip the interview" path: the Step-1.5 precondition gate forces an honest fork check, an unresolved fork bounces to brainstorm, and the grounding-check and user-review gates are retained unchanged. The reactive-deference failure class brainstorm exists to prevent is not reintroduced.
• Consistent with the toolchain's deepest commitment. The deciding→producing split mirrors the RED→GREEN split that keeps tdd/debug honest; specify is a co-equal third entry path, chosen by reflection, never a default.
• No drift. All four pipeline renderings and every cross- reference agree on the three-path shape (verified by audit).