From b9356eb7185b37585bdfb8795a61e95541bbb9b1 Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 4 Jun 2026 22:42:20 +0200 Subject: [PATCH] spec: specify spec-production entry path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a third dev-cycle entry path: a specify skill that produces an approved spec from given sources (settled in-context discussion or an exhaustive issue) with review but no interview. Splits brainstorm's deciding half from its producing half — brainstorm becomes optional discovery, specify becomes the sole production gate before planner, mirroring the RED->GREEN split that keeps tdd/debug honest. specify bounces to brainstorm on an unresolved design fork, the same discipline tdd uses. --- .../2026-06-04-specify-entry-path-design.md | 308 ++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 docs/specs/2026-06-04-specify-entry-path-design.md diff --git a/docs/specs/2026-06-04-specify-entry-path-design.md b/docs/specs/2026-06-04-specify-entry-path-design.md new file mode 100644 index 0000000..d305f97 --- /dev/null +++ b/docs/specs/2026-06-04-specify-entry-path-design.md @@ -0,0 +1,308 @@ +# `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).