spec: remove brainstorm-grounding-check draft (superseded by final spec)
This commit is contained in:
@@ -1,225 +0,0 @@
|
||||
# Brainstorm Grounding Check — Discussion Draft
|
||||
|
||||
**Date:** 2026-05-11
|
||||
**Status:** Discussion draft — input for a fresh brainstorm in a future session. NOT an approved spec.
|
||||
**Authors:** Brummel (orchestrator) + Claude
|
||||
|
||||
## Why this draft exists
|
||||
|
||||
On 2026-05-11 the iter 23.4 family (Eq/Ord prelude free fns) BLOCKED
|
||||
four times in a row on architectural prerequisites the parent spec
|
||||
had not anticipated. Three prep iters were merged on main (prep,
|
||||
prep2, prep3) before a fourth gap surfaced and the user stopped the
|
||||
chain: "Wäre es nicht sinnvoll, es einmal richtig zu machen, anstatt
|
||||
auf drei Pflaster noch ein viertes zu kleben?"
|
||||
|
||||
The repository was reset to the pre-session HEAD (`1625264`) and the
|
||||
day's commits discarded. This draft captures the diagnosis and the
|
||||
proposed pipeline change so a fresh brainstorm can take it as input.
|
||||
|
||||
## What we learned
|
||||
|
||||
### 1. Repeated BLOCKEDs are a spec-defect signal, not a plan-defect signal
|
||||
|
||||
When the same iter family blocks twice or more on related
|
||||
architectural prerequisites, the spec under-estimated the
|
||||
implementation surface. Patching with another prep iter accumulates
|
||||
band-aids on what is really one missing architectural commitment.
|
||||
The right response is to amend the spec; the wrong response is to
|
||||
continue patching.
|
||||
|
||||
Captured as user memory (`feedback_spec_over_plan_patches.md`).
|
||||
|
||||
### 2. Spec verification today is purely linguistic
|
||||
|
||||
The `brainstorm` skill's Step 7 (self-review) and Step 8
|
||||
(user-approval gate) are both linguistic:
|
||||
|
||||
- **Step 7 (self-review)** is a four-point checklist: placeholder
|
||||
scan, internal consistency, scope check, ambiguity check. None of
|
||||
these touches code.
|
||||
- **Step 8 (user-approval)** asks the user to read and approve. In
|
||||
practice the user does not have time for forensic code-reading.
|
||||
The spec gets approved on linguistic merits.
|
||||
|
||||
Nobody opens the codebase to check whether spec assertions about
|
||||
compiler behaviour are actually true. The architect agent
|
||||
(`ailang-architect`) does exactly this kind of code-vs-doc check —
|
||||
but only at milestone close, far too late.
|
||||
|
||||
### 3. Spec-23 illustrates the failure mode
|
||||
|
||||
Forensic reading of `docs/specs/2026-05-10-23-eq-ord-prelude.md`
|
||||
(created 2026-05-10 20:35 in commit `03b6d15`, approved 21:04 in
|
||||
commit `9c3d290`, 29 minutes apart):
|
||||
|
||||
The Data-flow section contains verbatim:
|
||||
|
||||
> "Polymorphic helpers (`fn cmp_max : forall a. Ord a => (a, a) -> a`)
|
||||
> work the same way: the typeclass-elaboration in 22b.3 inserts the
|
||||
> right monomorphised `compare__T` symbol per use site."
|
||||
|
||||
This was the load-bearing assumption. It is wrong: the 22b.3 path
|
||||
specialises class-method calls, not polymorphic free-fn calls. The
|
||||
assumption sat as a half-sentence in the spec, never explicitly
|
||||
flagged as an assumption, never verified against any existing green
|
||||
test. Three iter 23.4 BLOCKEDs on 2026-05-11 surfaced it the hard way.
|
||||
|
||||
The linguistic self-review caught nothing (text is internally
|
||||
consistent and unambiguous). The user-review caught nothing (the
|
||||
half-sentence reads plausible). Only a code-grounded prerequisite
|
||||
check would have caught this.
|
||||
|
||||
## Proposed addition to the pipeline
|
||||
|
||||
A new agent, dispatched between the spec draft and the user-approval
|
||||
gate.
|
||||
|
||||
### Role
|
||||
|
||||
Read the spec draft with fresh context (no sunk-cost from the
|
||||
brainstorm session). Extract its load-bearing assumptions — both
|
||||
explicit and implicit. For each assumption, search the existing
|
||||
codebase for a green fixture that ratifies it. Report status per
|
||||
assumption.
|
||||
|
||||
### Why fresh context
|
||||
|
||||
The brainstorm-driven orchestrator has spent 30+ minutes building
|
||||
the spec and is biased toward shipping it. A fresh agent has no such
|
||||
bias. The asymmetry mirrors how `ailang-architect` reviews
|
||||
code-vs-DESIGN.md drift today: without loyalty to the implementation
|
||||
that produced the drift.
|
||||
|
||||
### What counts as ratification
|
||||
|
||||
A committed, currently-green test. Not "code that does X exists"
|
||||
(open to interpretation), not "I recall this pattern works" (memory
|
||||
bias), not "another spec said it works" (transitive uncertainty). A
|
||||
green `cargo test` is concrete: it ran today, the symbol it pins
|
||||
exists, the assertion it makes holds.
|
||||
|
||||
Invariant in the planning phase: the workspace has no red fixtures.
|
||||
If a red fixture exists, the planning phase is not the right phase —
|
||||
something else needs fixing first.
|
||||
|
||||
### Pipeline placement
|
||||
|
||||
```
|
||||
brainstorm Step 5/6 (spec drafted)
|
||||
→ NEW: grounding-check agent (fresh context, read-only)
|
||||
→ all assumptions ratified
|
||||
→ Step 7 self-review, Step 8 user-approval-gate
|
||||
→ at least one assumption unratified
|
||||
→ spec draft discarded; Boss adds roadmap entry with the
|
||||
missing prerequisite as `depends on:`. The blocked idea
|
||||
waits until the prerequisite ships.
|
||||
→ planner ...
|
||||
```
|
||||
|
||||
The discard-and-add-to-roadmap default (Boss-overridable) rests on
|
||||
the observation that prerequisites can take days or weeks to ship.
|
||||
By then, the original spec's framing is likely stale; re-brainstorming
|
||||
on the shipped prerequisite is more honest than dusting off the old
|
||||
draft.
|
||||
|
||||
## Open design questions (to brainstorm in the next session)
|
||||
|
||||
The following decisions are intentionally NOT made in this draft.
|
||||
They are the Q&A material for the next session's brainstorm.
|
||||
|
||||
1. **How does the agent define an "assumption"?**
|
||||
Strictness scale:
|
||||
- (a) every spec assertion about compiler behaviour;
|
||||
- (b) only assertions that extend an existing mechanism beyond its
|
||||
current scope;
|
||||
- (c) only assertions the agent's own extraction step flags.
|
||||
Each has different false-positive / false-negative tradeoffs.
|
||||
|
||||
2. **What format does the report take?**
|
||||
Per-assumption: claim, search query / test names checked, status
|
||||
(ratified / unratified). Aggregate status at the top. Probably
|
||||
mirrors the existing spec/quality reviewer output formats.
|
||||
|
||||
3. **Where does the agent live in the skill repository?**
|
||||
Frontmatter, reading list, iron-law section, output format.
|
||||
Naming convention candidates: `ailang-grounding-check`,
|
||||
`ailang-spec-premise-auditor`, `ailang-prerequisite-check`.
|
||||
|
||||
4. **What changes in `skills/brainstorm/SKILL.md`?**
|
||||
New step between current 6 and 7. Hard-gate language. Failure-mode
|
||||
procedure (the spec-discard / roadmap-entry default).
|
||||
|
||||
5. **What changes in `docs/roadmap.md`?**
|
||||
How are deferred ideas annotated. The existing `depends on:` line
|
||||
type may already suffice; or a new "blocked-on-prerequisite"
|
||||
status label is needed.
|
||||
|
||||
6. **What's the test-naming convention that makes ratification
|
||||
searches feasible?**
|
||||
Today tests are scattered. If the agent has to grep for "is there
|
||||
a green test ratifying mono-specialisation-of-polymorphic-free-fns?",
|
||||
the answer needs to come out in a finite query. Either we
|
||||
standardise test-naming so the search is mechanical, or we accept
|
||||
that the agent makes a judgement call and document its heuristic.
|
||||
|
||||
7. **What happens to the discarded brainstorm artefacts?**
|
||||
Brainstorm conversation, partial spec draft. Do they go to a
|
||||
`docs/scratchpad/` ledger, or are they lost? The cost of losing
|
||||
them is "the same idea gets re-brainstormed cold in 3 months"; the
|
||||
cost of keeping them is "stale drafts linger and bias future
|
||||
thinking". The user has already indicated (a) is the preferred
|
||||
default — Roadmap-only, drafts discarded — but the question stays
|
||||
open for the next session to ratify formally.
|
||||
|
||||
8. **Does this agent run on existing specs too?**
|
||||
Spec-23 still exists at `docs/specs/2026-05-10-23-eq-ord-prelude.md`,
|
||||
approved but mid-flight (iters 23.1–23.3 shipped). Should the new
|
||||
agent be run against it retroactively? Or do existing specs
|
||||
grandfather past the new check?
|
||||
|
||||
## Adjacent observations (not in scope for this draft)
|
||||
|
||||
Recorded for future skill-system work, not part of the grounding-check
|
||||
brainstorm itself:
|
||||
|
||||
- **Branch-hygiene papercut.** The `ailang-implement-orchestrator`
|
||||
agent ends each run with the worktree on `iter/<iter_id>`. The Boss
|
||||
merge step needs `git switch main` before any further commit;
|
||||
otherwise commits land on the iter branch by mistake. This happened
|
||||
three times on 2026-05-11. Worth a one-line addition to
|
||||
`skills/implement/SKILL.md` Step 3 prelude.
|
||||
|
||||
- **Plan-recon dispatches only after spec-approval.** Today
|
||||
`ailang-plan-recon` maps files for the planner but never sees the
|
||||
spec before it is approved. The grounding-check agent could
|
||||
conceivably re-use plan-recon's read-only file-survey discipline.
|
||||
Worth considering during the next brainstorm — same recon agent,
|
||||
earlier dispatch with a different brief.
|
||||
|
||||
## Memory entries already captured
|
||||
|
||||
These should NOT be re-derived in the next session — they are
|
||||
persistent and live outside the project tree at
|
||||
`~/.claude/projects/-home-brummel-dev-ailang/memory/`:
|
||||
|
||||
- `feedback_spec_over_plan_patches.md` — Repeated BLOCKEDs = spec
|
||||
defect, not plan defect.
|
||||
- `feedback_plain_german_no_jargon.md` — Chat in plain German, no
|
||||
self-coined Anglo-Deutsch terms when writing for the user.
|
||||
|
||||
## How to start the next session
|
||||
|
||||
1. Read this draft as the input.
|
||||
2. Invoke the `brainstorm` skill with the topic "brainstorm
|
||||
grounding-check agent".
|
||||
3. The skill does its Q&A; this draft pre-answers the WHY and
|
||||
pre-states the open questions, so the Q&A can focus on the
|
||||
eight open design questions above.
|
||||
4. The output is a proper spec at
|
||||
`docs/specs/YYYY-MM-DD-brainstorm-grounding-check.md`, then a
|
||||
plan, then implementation — standard pipeline.
|
||||
5. Note the bootstrap irony: the new agent will not yet exist when
|
||||
the brainstorm produces a spec for the new agent itself. The
|
||||
first run of the new check happens on the second spec written
|
||||
after it ships, not on its own spec.
|
||||
Reference in New Issue
Block a user