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