AILang/skills/brainstorm/SKILL.md

---
name: brainstorm
description: Use when a new milestone is starting — gathers requirements, explores 2-3 approaches with trade-offs, presents a sectioned design with user approval, writes the spec to docs/specs/. Hard-gate before any plan or code work; applies even when the user says they have a clear vision.
---

# brainstorm — milestone spec generator

> **Violating the letter of these rules is violating the spirit.**

## Overview

The spec is where the orchestrator does the design work. It is the
artefact that future iterations, the architect agent, and any future
LLM read to understand WHAT the milestone delivers and WHY. Skipping
the spec means shipping the user's intuition unfiltered, which is
exactly the reactive-deference failure mode AILang's orchestrator
discipline exists to prevent.

It produces specs at `docs/specs/<milestone>.md`.

## When to Use / Skipping

Triggers:
- A new milestone is starting (e.g. user proposes a new feature
  area, a new subsystem, or a major refactor of an existing one).
- A milestone-scope spec is missing for an existing line of work
  and one is needed retroactively.

**Skipping is permitted only** for:
- A bug-fix iteration (use `debug` directly).
- A tidy iteration (use `audit` directly).
- A trivial mechanical edit (≤1 file, ≤30 LOC, no design judgement).

**Skipping is not permitted** for:
- A user request framed as "I have a clear vision, just plan it".
- A milestone described as "small, only two iterations".
- A milestone where you are confident you know what to build.

The first two cases above are the most common pressure to skip;
both are explicitly resisted by this skill (see Common
Rationalisations).

## The Hard-Gate

```
NO IMPLEMENTATION, SCAFFOLDING, OR DOWNSTREAM SKILL INVOCATION
UNTIL A SPEC HAS BEEN PRESENTED AND THE USER HAS APPROVED IT.
```

The hard-gate applies regardless of perceived simplicity. The spec
can be short for a small milestone (a few sections), but it MUST
exist and be approved before any plan or code work begins.

## The Process

### Step 1 — Explore project context

Before asking any clarifying questions:
- Read the latest entries linked from `docs/journals/INDEX.md` (most recent
  milestones, current state).
- Skim `design/INDEX.md` (walk to the relevant contracts) for the invariants the new milestone
  might touch.
- `git log --oneline -20` to see what just shipped.
- Identify scope: is this one milestone, or does it need to be
  decomposed into sub-milestones first? If multi-subsystem, decompose.

### Step 2 — Ask clarifying questions, one at a time

Multiple-choice when possible (easier to answer). One question per
message — no batching. Focus on:
- **Purpose:** what problem does this solve?
- **Constraints:** what semantic / performance / compatibility
  invariants must hold?
- **Success criteria:** how do we know it shipped?
- **Scope:** what is OUT of scope?

### Step 3 — Propose 2-3 approaches with trade-offs

Lead with your recommended option and explain why. Each approach
gets:
- core idea (1-2 sentences)
- **the AILang program first, code not prose.** The *primary*
  artifact is the `.ail` (Form-A) program that should work under
  this approach — the code the language is *for*. Show it. The
  implementation shape (changed struct/signature/match-arm,
  before → after) is *secondary supporting* detail — "also useful,
  not the point" — include it but never let it stand in for the
  `.ail`. "The approach extends the struct with a field" is not an
  approach; the `.ail` it makes work (or correctly reject) is.
- substantive trade-offs (semantic fit, schema impact, performance,
  composability)
- effort observation (NOT effort as rationale — see CLAUDE.md
  "Design rationale ≠ implementation effort")

Wait for user choice before proceeding.

### Step 4 — Apply the feature-acceptance criterion

A feature ships only if all three hold:
- An LLM author (= future me) naturally produces code that uses it,
  AND
- The feature measurably improves correctness or removes redundancy,
  AND
- It reintroduces no bug class the core constraint exists to
  eliminate. Criterion 1 does not discriminate — an LLM reaches for
  *every* construct native to its imperative training distribution,
  so "the LLM reaches for it" is satisfied by exactly the constructs
  AILang most deliberately refuses. A documentation note is not a
  reshape: the gate is whether the wrong code fails to typecheck, not
  whether a guideline advises against it.

Aesthetic appeal does not count. Human ergonomics do not count. If
the answer to any of the three is "I'm not sure", the feature is
probably not ready. The full criterion (with the canonical worked
example — see the criterion text) lives in
`design/contracts/feature-acceptance.md`; this skill is the gate that
applies it during spec writing.

**Clause 1 is unjudgeable without the worked author code.** For any
milestone with authoring surface, the spec MUST contain the actual
Form-A (`.ail`) example an LLM author would write — and that example
*is* the clause-1 evidence. A prose assertion ("an LLM naturally
reaches for X") with no shown code is exactly the unfalsifiable
hand-wave the criterion exists to prevent: write the code the LLM
would write, then judge whether it is in fact what the criterion
demands. For an infrastructure milestone with **no** author surface
there is still concrete AILang code: show the actual `.ail` the
milestone *delivers* — frequently a test fixture **whose correct
behaviour is rejection** (wrong code must fail to typecheck — the
clause-3 discriminator) — plus a *minimal, honest* slice of the
north-star program the infrastructure exists to serve (provisional
surface explicitly flagged, never a vague non-normative hand-wave).
"This milestone has no surface so there's no AILang code to show" is
the rationalisation to refuse: an infra milestone that cannot be
tied to concrete AILang code is speculative infra. (AILang's own
thesis is structured concrete form over prose description; a
spec that describes code in prose is incoherent with the language it
specifies.)

### Step 5 — Present design in sections

Scale each section to its complexity (a few sentences if
straightforward, up to 200-300 words if nuanced). Cover:
- Architecture
- Components
- Data flow
- Error handling
- Testing strategy

**The AILang program is the headline; the implementation shape is
supporting.** The `## Concrete code shapes` section leads with the
`.ail` (Form-A) program — the worked author example for a surface
milestone (= the Step-4 clause-1 evidence), or the delivered
fixture-and-north-star for an infra milestone (per Step 4). The
before → after implementation shape (struct / signature / match-arm)
follows as a clearly secondary subsection — "also useful, not the
point" — never first, never a substitute for the `.ail`. Prose may
*explain* code, never *replace* it. Exact bytes/line-numbers remain
the planner's job (planner Iron Law) — the spec owns the *shape*,
shown, with the AILang program foremost.

Ask after each section whether it looks right. Be ready to revisit
earlier sections if a later one surfaces a contradiction.

### Step 6 — Write the spec

Path: `docs/specs/YYYY-MM-DD-<milestone>.md`.

Structure:

```markdown
# <Title> — Design Spec

**Date:** YYYY-MM-DD
**Status:** Draft — awaiting user spec review
**Authors:** Brummel (orchestrator) + Claude

## Goal
## Architecture
## Concrete code shapes
## Components
## Data flow
## Error handling
## Testing strategy
## Acceptance criteria
```

`## Concrete code shapes` is mandatory and **leads with the AILang
program**: the worked `.ail` author example for an authoring-surface
milestone (= the Step-4 clause-1 evidence), or — for a no-surface
infra milestone — the `.ail` the milestone *delivers* (often a
must-fail fixture) plus a minimal honest north-star slice (Step 4).
The before → after implementation shape for each load-bearing change
follows as an explicitly secondary subsection, never first.

### Step 7 — Self-review

Inline checklist (not a subagent dispatch):

1. **Placeholder scan:** any "TBD", "TODO", incomplete sections,
   vague requirements? Fix.
2. **Internal consistency:** sections must not contradict.
   Architecture must match component descriptions.
3. **Scope check:** focused enough for one plan, or does it need
   sub-milestone decomposition?
4. **Ambiguity check:** could any requirement be interpreted two
   ways? If so, pick one and make it explicit.
5. **Concrete-code check:** does `## Concrete code shapes` exist and
   carry before → after code for every load-bearing change (plus the
   worked `.ail` example for an authoring-surface milestone)? A
   load-bearing change described only in prose is a self-review
   failure to fix, exactly like a placeholder.

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 `<path>::<name>` 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`):**

1. Delete the just-written spec file from the working tree
   (`rm docs/specs/<spec_filename>.md` — a Bash-level delete on the
   working tree, NOT `git rm`; the file was never committed).
2. Append a roadmap entry to `docs/roadmap.md` pointing forward to a
   future re-brainstorm, under the appropriate priority bucket:

   ```markdown
   - [ ] **[<kind>]** <idea title> — <one-line description>
     - context: <why this is deferred>
     - depends on: <name of the unratified mechanism>
   ```

3. Tell the user the spec was retired and which roadmap entry was
   added. The user / Boss commits the roadmap edit (suggested
   commit subject: `spec: retire <spec topic> — depends on
   <unratified mechanism>`).

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.

**Re-dispatch on any post-PASS edit.** The grounding-check PASS
report is bound to the exact bytes of the spec at dispatch time.
Any subsequent edit to the spec file — Boss-side polish, a
user-requested change in free chat, a wording tighten, anything —
invalidates the PASS report and requires a fresh dispatch of
`ailang-grounding-check` before Step 8 commit. Step 7.5 is the
*last* step that touches the spec file; nothing slips between it
and the commit.

### Step 8 — User-review gate

The spec sits in the working tree as an unstaged file. Tell the user:

> Spec written to `<path>` (uncommitted). Please review it and let
> me know if you want changes before we start the implementation
> plan. The Boss will commit it once you approve.

Wait for the user's response. If they request changes, edit the
file in place (still uncommitted), **re-run Step 7 AND re-dispatch
Step 7.5** (the previous PASS report no longer covers the edited
bytes), then return here. Only proceed to the next step after
approval AND a fresh Step 7.5 PASS.

The Boss commits the approved spec after the user signs off
(suggested commit subject: `spec: <milestone> <topic>`). The
brainstorm skill does not perform the commit itself.

### Step 9 — Hand off to `planner`

The terminal state of `brainstorm` is invoking `planner`. NO other
skill is invoked from `brainstorm`. NO direct jump to `implement`.

Hand off carries:
- path to `docs/specs/<milestone>.md`
- iteration scope ("the first iteration covers section X+Y of the
  spec")

## Handoff Contract

| Direction | Carrier |
|-----------|---------|
| user → `brainstorm` | new milestone request |
| `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 added to `docs/roadmap.md` in the working tree, spec file deleted from the working tree; Boss commits the roadmap edit |

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| "User says 'clear vision, just plan it' — skip the spec" | "Clear vision" is a starting point, not a spec. The user's intuition hasn't priced in semantic commitments (RC, uniqueness, codegen, schema). Write the spec; frame it as "load-bearing decisions this idea forces on us". |
| "Milestone is small, two iterations, no spec needed" | Iteration count isn't the metric — feature surface is. A two-iter feature touching design/ ledger invariants needs a spec; a CLI flag does not. Assess what the feature changes in invariants. |
| "Three approaches in, none feel right, ship the least bad" | Three unsatisfying approaches usually means the problem is mis-framed. Stop, write a JOURNAL entry capturing the three approaches and what fails about each, sleep on it. End-of-day pressure is the worst signal to resolve a design fork. |
| "User is busy, present my own design without Q&A" | Reactive deference disguised as decisiveness. The Q&A surfaces constraints the user hasn't articulated; skipping it means shipping the user's defaults, not their intent. |
| "Spec exists from previous milestone, append to it" | New milestone = new spec file. The architect agent reads spec files per milestone; mixing scopes makes drift review unreadable. |
| "Approaches A, B, C are all bad — proceed with A" | This is exactly the moment to surface "the problem is mis-framed" rather than ratify a known-bad shape into the design/ ledger. JOURNAL the impasse, escalate to user. |
| "Just polishing a wording after PASS, no need to re-dispatch" | The grounding-check report attests to specific bytes. A polish edit changes the bytes; the previous attestation no longer covers them. Re-dispatch is cheap; the alternative is a commit with an attestation that doesn't match the file. |
| "The shape is clear from the prose, I don't need to paste the code" | If it's clear, pasting it is free; if pasting it is hard, it wasn't clear. Clause 1 is unjudgeable without the worked `.ail`; "an LLM reaches for it" with no shown code is the exact hand-wave the criterion exists to kill. Prose about code is incoherent with a language whose thesis is structured-form-over-prose. |

## Red Flags — STOP

- "Skip the spec" thoughts (any flavour)
- "One paragraph is enough"
- "User said it's clear, who am I to push back"
- "The 2-3 approaches all suck, just pick one"
- Skipping Step 7 self-review because "I wrote it carefully"
- A load-bearing change described in prose with no before → after
  code block; an authoring-surface milestone with no worked `.ail`
  example
- Editing the spec file after a Step 7.5 PASS without re-dispatching
- Jumping straight from spec to `implement` (must go via `planner`)
- Inventing a design rationale that's actually about effort, not
  semantics

## Cross-references

- **Project source:** `design/contracts/feature-acceptance.md`
  — gate this skill applies during spec writing.
- **Output target:** `skills/planner/SKILL.md` — only valid next
  skill.
- **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.