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