---
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 in `docs/JOURNAL.md` (most recent
  milestones, current state).
- Skim `docs/DESIGN.md` 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)
- 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:
- An LLM author (= future me) naturally produces code that uses it,
  AND
- The feature measurably improves correctness or removes redundancy.

Aesthetic appeal does not count. Human ergonomics do not count. If
the answer to either criterion is "I'm not sure", the feature is
probably not ready. The full criterion lives in `docs/DESIGN.md`
("Feature-acceptance criterion"); this skill is the gate that
applies it during spec writing.

### 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

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
## Components
## Data flow
## Error handling
## Testing strategy
## Acceptance criteria
```

### 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.

Fix issues inline. No need to re-review — fix and commit.

### Step 8 — Commit + user-review gate

```bash
git add docs/specs/<filename>.md
git commit -m "spec: <milestone> <topic>"
```

Tell the user:

> Spec written and committed to `<path>`. Please review it and
> let me know if you want to make any changes before we start the
> implementation plan.

Wait for the user's response. If they request changes, make them
and re-run Step 7. Only proceed to the next step after approval.

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

The terminal state of `brainstorm` is invoking `plan`. 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` → `plan` | path to spec + iteration scope |

## 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.md 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 DESIGN.md. JOURNAL the impasse, escalate to user. |

## 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"
- Jumping straight from spec to `implement` (must go via `plan`)
- Inventing a design rationale that's actually about effort, not
  semantics

## Cross-references

- **Project source:** `docs/DESIGN.md` "Feature-acceptance
  criterion" — gate this skill applies during spec writing.
- **Output target:** `skills/plan/SKILL.md` — only valid next
  skill.
- **No private agents.** This skill is dialogue-driven.
