audit(specify): close cycle — repair planner, grounding-check, schema drift

Architect drift review (cycle 9e8b9ec..HEAD) returned drift_found. Three
cycle-introduced items, all repaired here as tidy edits:

- planner/SKILL.md: the cycle never touched it (recon never scoped it,
  the feat commit body's "every pipeline rendering agrees" over-claimed).
  Its Handoff Contract still named `brainstorm → planner` and the bounce
  `planner → brainstorm`; the Input-source cross-ref and two
  rationalisation rows still pointed at brainstorm as the spec producer.
  All repointed to specify (specify produces and owns the spec; brainstorm
  is the optional discovery stage upstream of it). The skip rule now lists
  specify in the design path tdd bypasses.
- specify/agents/grounding-check.md: the agent move left one stale pair —
  "self-review (Step 7) and user-approval (Step 8)" were brainstorm's old
  numbers; in specify they are Step 4 and Step 6.
- profile-schema + template: the `optional: true` per-phase key I
  introduced in the plan was undocumented AND rested on a semantic error —
  `brainstorm: { gates: [specify] }` reads as "specify cannot start until
  brainstorm has run", which is false (specify enters directly from
  sources). Corrected to `brainstorm: {}` (an active phase with no hard
  gate of its own, like implement); specify keeps `gates: [planner]` as
  the one real hard gate. The optional key is gone; brainstorm's
  optionality lives in the skip rules and SKILL prose, where it belongs.

Why these escaped the cycle's own grep suite: the consistency greps used
`brainstorm *-> *planner`, which does not match the real renderings
`` `brainstorm` -> `planner` `` (backticks between the words). The same
filter-string blind spot recurred twice this session; the verification
greps here tolerate optional backticks.

Pre-existing debt (NOT cycle-introduced), filed as backlog Brummel/Skills
issue #5 rather than fixed here: docs/migration.md's layout tree and
README's migration-status both predate tdd/glossary/pseudo/issue/
postmortem and misdescribe the roster.

Verdict: cycle drift-clean after these repairs (carry-on). No regression
gate (prose repo, no scripts). Not a milestone close.
This commit is contained in:
2026-06-04 23:25:03 +02:00
parent 4f83305525
commit f7758818ab
4 changed files with 13 additions and 14 deletions
+2 -4
View File
@@ -187,9 +187,7 @@ Per-phase configuration. Each phase has its own sub-map.
```yaml ```yaml
pipeline: pipeline:
brainstorm: brainstorm: {} # optional discovery front-end; no hard gate of its own
gates: [specify] # optional discovery; hands ratified design to specify
optional: true # skipped when the design is settled in the sources
specify: specify:
gates: [planner] # core node — planner cannot start until the spec is approved gates: [planner] # core node — planner cannot start until the spec is approved
planner: planner:
@@ -255,7 +253,7 @@ git:
close_marker: "closes #N" close_marker: "closes #N"
pipeline: pipeline:
brainstorm: { gates: [specify], optional: true } brainstorm: {} # optional discovery; no hard gate
specify: { gates: [planner] } specify: { gates: [planner] }
planner: { gates: [implement] } planner: { gates: [implement] }
implement: {} implement: {}
+9 -8
View File
@@ -38,8 +38,8 @@ May be skipped when:
the plan (handoff goes straight to `implement` mini-mode). the plan (handoff goes straight to `implement` mini-mode).
- The work is a test-specifiable feature routed through `tdd`, - The work is a test-specifiable feature routed through `tdd`,
where the RED executable-spec IS the plan (handoff goes where the RED executable-spec IS the plan (handoff goes
straight to `implement` mini-mode). `tdd` skips both straight to `implement` mini-mode). `tdd` skips the whole
`brainstorm` and `planner`. design path — `brainstorm`, `specify`, and `planner`.
- The work is a trivial mechanical edit (per the project's - The work is a trivial mechanical edit (per the project's
CLAUDE.md "trivial mechanical edits" carve-out). CLAUDE.md "trivial mechanical edits" carve-out).
@@ -253,9 +253,9 @@ The planner skill does not perform the commit itself.
| Direction | Carrier | | Direction | Carrier |
|-----------|---------| |-----------|---------|
| `brainstorm``planner` | path to the spec under `paths.spec_dir` + iteration scope ("this iteration covers spec section X+Y") | | `specify``planner` | path to the spec under `paths.spec_dir` + iteration scope ("this iteration covers spec section X+Y") |
| `planner``implement` | path to the plan under `paths.plan_dir` + optional task-range focus | | `planner``implement` | path to the plan under `paths.plan_dir` + optional task-range focus |
| `planner``brainstorm` (bounce) | spec contains placeholders or contradictions: name the offending section, request revision | | `planner``specify` (bounce) | spec contains placeholders or contradictions: name the offending section, request revision |
## Common Rationalisations ## Common Rationalisations
@@ -266,8 +266,8 @@ The planner skill does not perform the commit itself.
| "Spec is recent, I wrote it, plan from memory" | Memory diverges from disk. 15 minutes of re-reading is the cheapest insurance in the cycle. | | "Spec is recent, I wrote it, plan from memory" | Memory diverges from disk. 15 minutes of re-reading is the cheapest insurance in the cycle. |
| "Step 5 'implement the parser' is fine, I'll detail it at execution time" | Then it's not a step, it's a wish. Steps are bite-sized OR the plan isn't done. | | "Step 5 'implement the parser' is fine, I'll detail it at execution time" | Then it's not a step, it's a wish. Steps are bite-sized OR the plan isn't done. |
| "Task 7 is similar to Task 4, just say so" | The executor may read tasks out of order. Repeat the code. | | "Task 7 is similar to Task 4, just say so" | The executor may read tasks out of order. Repeat the code. |
| "The spec has a TBD too, I can pass it through" | Bounce back to `brainstorm`. Plans inherit spec gaps; spec gaps are not plan placeholders. | | "The spec has a TBD too, I can pass it through" | Bounce back to `specify`. Plans inherit spec gaps; spec gaps are not plan placeholders. |
| "The example program came straight from the spec, it must be valid" | The spec's code blocks are hypotheses, not verified bytes — brainstorm's parse gate can be skipped and a post-spec edit can break them. Re-parse every surface-language body you inline; this is the last line before the implementer hits it (issue #1 Fix 4). | | "The example program came straight from the spec, it must be valid" | The spec's code blocks are hypotheses, not verified bytes — specify's parse gate can be skipped and a post-spec edit can break them. Re-parse every surface-language body you inline; this is the last line before the implementer hits it (issue #1 Fix 4). |
## Red Flags — STOP ## Red Flags — STOP
@@ -284,8 +284,9 @@ The planner skill does not perform the commit itself.
## Cross-references ## Cross-references
- **Input source:** `../brainstorm/SKILL.md` — produces the - **Input source:** `../specify/SKILL.md` — produces the
spec this skill consumes. spec this skill consumes (reached directly from settled
sources, or via the optional `../brainstorm` discovery stage).
- **Output target:** `../implement/SKILL.md` — runs the plan - **Output target:** `../implement/SKILL.md` — runs the plan
task-by-task. task-by-task.
- **Agents dispatched:** - **Agents dispatched:**
+1 -1
View File
@@ -19,7 +19,7 @@ demands that the spec — not the plan — be corrected at the
root. root.
This agent is dispatched between specify's linguistic This agent is dispatched between specify's linguistic
self-review (Step 7) and user-approval (Step 8). The self-review (Step 4) and user-approval (Step 6). The
specify-driven orchestrator has spent its budget building specify-driven orchestrator has spent its budget building
the spec and is biased toward shipping it. You, by contrast, the spec and is biased toward shipping it. You, by contrast,
arrive fresh: no sunk-cost, no investment in the framing. arrive fresh: no sunk-cost, no investment in the framing.
+1 -1
View File
@@ -67,7 +67,7 @@ notifications:
# command: "" # e.g. "~/.claude/notify.sh"; boss falls back to chat if empty # command: "" # e.g. "~/.claude/notify.sh"; boss falls back to chat if empty
pipeline: pipeline:
brainstorm: { gates: [specify], optional: true } # optional discovery; skipped when design is settled brainstorm: {} # optional discovery front-end; no hard gate of its own
specify: { gates: [planner] } # core node: spec-production gate before planner specify: { gates: [planner] } # core node: spec-production gate before planner
planner: { gates: [implement] } planner: { gates: [implement] }
implement: {} implement: {}