From f7758818ab9510565d03b471453452b6b8c0c04d Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 4 Jun 2026 23:25:03 +0200 Subject: [PATCH] =?UTF-8?q?audit(specify):=20close=20cycle=20=E2=80=94=20r?= =?UTF-8?q?epair=20planner,=20grounding-check,=20schema=20drift?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/profile-schema.md | 6 ++---- planner/SKILL.md | 17 +++++++++-------- specify/agents/grounding-check.md | 2 +- templates/project-profile.yml | 2 +- 4 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/profile-schema.md b/docs/profile-schema.md index 35aaade..ec8c757 100644 --- a/docs/profile-schema.md +++ b/docs/profile-schema.md @@ -187,9 +187,7 @@ Per-phase configuration. Each phase has its own sub-map. ```yaml pipeline: - brainstorm: - gates: [specify] # optional discovery; hands ratified design to specify - optional: true # skipped when the design is settled in the sources + brainstorm: {} # optional discovery front-end; no hard gate of its own specify: gates: [planner] # core node — planner cannot start until the spec is approved planner: @@ -255,7 +253,7 @@ git: close_marker: "closes #N" pipeline: - brainstorm: { gates: [specify], optional: true } + brainstorm: {} # optional discovery; no hard gate specify: { gates: [planner] } planner: { gates: [implement] } implement: {} diff --git a/planner/SKILL.md b/planner/SKILL.md index b3ab834..8368b26 100644 --- a/planner/SKILL.md +++ b/planner/SKILL.md @@ -38,8 +38,8 @@ May be skipped when: the plan (handoff goes straight to `implement` mini-mode). - The work is a test-specifiable feature routed through `tdd`, where the RED executable-spec IS the plan (handoff goes - straight to `implement` mini-mode). `tdd` skips both - `brainstorm` and `planner`. + straight to `implement` mini-mode). `tdd` skips the whole + design path — `brainstorm`, `specify`, and `planner`. - The work is a trivial mechanical edit (per the project's CLAUDE.md "trivial mechanical edits" carve-out). @@ -253,9 +253,9 @@ The planner skill does not perform the commit itself. | 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` → `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 @@ -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. | | "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. | -| "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 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 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 — 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 @@ -284,8 +284,9 @@ The planner skill does not perform the commit itself. ## Cross-references -- **Input source:** `../brainstorm/SKILL.md` — produces the - spec this skill consumes. +- **Input source:** `../specify/SKILL.md` — produces the + spec this skill consumes (reached directly from settled + sources, or via the optional `../brainstorm` discovery stage). - **Output target:** `../implement/SKILL.md` — runs the plan task-by-task. - **Agents dispatched:** diff --git a/specify/agents/grounding-check.md b/specify/agents/grounding-check.md index 72ad004..cffbc9f 100644 --- a/specify/agents/grounding-check.md +++ b/specify/agents/grounding-check.md @@ -19,7 +19,7 @@ demands that the spec — not the plan — be corrected at the root. 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 the spec and is biased toward shipping it. You, by contrast, arrive fresh: no sunk-cost, no investment in the framing. diff --git a/templates/project-profile.yml b/templates/project-profile.yml index 389d39f..970df0d 100644 --- a/templates/project-profile.yml +++ b/templates/project-profile.yml @@ -67,7 +67,7 @@ notifications: # command: "" # e.g. "~/.claude/notify.sh"; boss falls back to chat if empty 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 planner: { gates: [implement] } implement: {}