diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index c655fa2..7afe571 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -149,6 +149,48 @@ Inline checklist (not a subagent dispatch): Fix issues inline. No need to re-review — fix and commit. +### Step 7.5 — Grounding-Check Agent (hard-gate) + +Dispatch the read-only `ailang-grounding-check` agent. The agent +reads the just-written spec with fresh context, extracts its +load-bearing assumptions about current compiler / checker / codegen +/ schema behaviour, and for each one searches the workspace for a +currently-green test that ratifies it. + +Dispatch carrier: + +| Field | Content | +|-------|---------| +| `spec_path` | path to the spec just written in Step 6 | +| `iteration_scope` | which sections cover the imminent first iteration (verbatim from the brainstorm session) | + +The agent returns a `PASS` / `BLOCK` / `INFRA_ERROR` report. Boss +interpretation: + +| Agent status | Boss action | +|--------------|-------------| +| `PASS` | Proceed to Step 8. The report goes into the brainstorm chat for the record. | +| `BLOCK` | Present the report to the user. User either: (a) accepts discard → execute the failure-mode procedure below; or (b) overrides in free chat ("Test `::` ratifies that") → log the override note in the brainstorm chat and proceed to Step 8. | +| `INFRA_ERROR` | Abort the brainstorm. The spec stays as-is on disk; debug the workspace out-of-band and re-dispatch the agent. | + +**Failure-mode procedure (no-override `BLOCK`):** + +```bash +git rm docs/specs/.md +# Append a roadmap entry pointing forward to a future re-brainstorm: +# - [ ] **[]** +# - context: +# - depends on: +$EDITOR docs/roadmap.md # add the entry under the appropriate priority bucket +git add docs/roadmap.md +git commit -m "spec: retire — depends on " +``` + +After the failure-mode procedure runs, the brainstorm session ENDS. +There is no Step 8, no Step 9. The idea is parked until the +dependency ships, at which point a fresh brainstorm session +re-derives the spec from scratch. + ### Step 8 — Commit + user-review gate ```bash @@ -180,7 +222,9 @@ Hand off carries: | Direction | Carrier | |-----------|---------| | user → `brainstorm` | new milestone request | -| `brainstorm` → `planner` | path to spec + iteration scope | +| `brainstorm` → `ailang-grounding-check` (Step 7.5) | `spec_path` + `iteration_scope` | +| `brainstorm` → `planner` (Step 9, on PASS or overridden BLOCK) | path to spec + iteration scope | +| `brainstorm` → roadmap (Step 7.5, on no-override BLOCK) | `depends on:` entry, spec deleted | ## Common Rationalisations @@ -210,10 +254,15 @@ Hand off carries: criterion" — gate this skill applies during spec writing. - **Output target:** `skills/planner/SKILL.md` — only valid next skill. -- **No private agents.** This skill is dialogue-driven. The Boss - MAY ad-hoc dispatch `skills/planner/agents/ailang-plan-recon.md` - during Step 1 when the milestone enters code territory the Boss - has not recently read; this is opt-in and not part of the standard - process. Rationale: brainstorm's recon phase is interwoven with - the user Q&A — see `docs/specs/2026-05-11-plan-recon-subagent.md` - for the full reasoning. +- **Private agent:** `skills/brainstorm/agents/ailang-grounding-check.md` + — dispatched in Step 7.5 as a hard-gate. The agent reads the spec + with fresh context and reports PASS / BLOCK / INFRA_ERROR. See + `docs/specs/2026-05-11-brainstorm-grounding-check.md` for the + design rationale. +- **Ad-hoc dispatch.** The Boss MAY also ad-hoc dispatch + `skills/planner/agents/ailang-plan-recon.md` during Step 1 when + the milestone enters code territory the Boss has not recently + read; this is opt-in and not part of the standard process. + Rationale: brainstorm's recon phase is interwoven with the user + Q&A — see `docs/specs/2026-05-11-plan-recon-subagent.md` for the + full reasoning.