Skills/brainstorm/SKILL.md

---
name: brainstorm
description: Use when a new cycle is starting and the design is NOT yet settled — enumerates the load-bearing design forks, populates them with a parallel swarm of grounded synthetic-user stances instead of a serial interview, triages the result (forks the swarm settles on a cited ground are decided; forks it splits on are the user's call), then hands the ratified design to specify. The optional discovery front-end; when the design is already settled in the sources, skip to specify directly. Applies even when the user says they have a clear vision.
---

# brainstorm — cycle discovery front-end

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

## Overview

Discovery is where the orchestrator does the *deciding* work — surfacing the
load-bearing forks a new cycle forces, resolving the ones it can ground an
answer for, and putting the rest to the user. It is the front-end that
settles a genuine design fork before any spec is written. Skipping it when the
design is genuinely open means shipping the user's intuition unfiltered, which
is exactly the reactive-deference failure the orchestrator discipline exists
to prevent.

What `brainstorm` no longer does is run a **serial interview** — one question
per message, a per-section ratification gate — to get there. That ceremony
spent ~10 blocking round-trips per cycle to catch a divergence from the
orchestrator's recommendation that, across a whole project, materialises about
once. Instead `brainstorm` **populates the design space in parallel**: it
enumerates the forks, dispatches a swarm of grounded, genuinely-opposed
synthetic-user stances to answer them, and triages the result. Where the
stances converge on a *cited* common ground the fork was derivable — it is
decided, and the user only vetoes. Where they genuinely split, no source
settles it — it is a **direction fork**, and that is the user's call. Direction
is never delegated downstream; it is set here, by the user, on exactly the
forks that turn out to be theirs.

`brainstorm` does not write the spec. Its terminal state is handing the
ratified design to `specify` (the spec-production core), which applies the
acceptance criterion, writes the spec under `docs/specs`, runs the gates, and
takes sign-off. When the design is *already* settled in the sources,
`brainstorm` is skipped entirely and the work enters through `specify`.

## When to Use / Skipping

Triggers:

- A new cycle is starting (a new feature area, a new subsystem, or a major
  refactor of an existing one) whose design is genuinely open.
- A cycle-scope spec is missing for an existing line of work and one is needed
  retroactively, and the design behind it was never settled.

**Skip `brainstorm` (enter through the named alternative) for:**

- A design already settled in the sources — an exhaustive issue, a long
  in-context discussion, settled design docs. Use `specify` directly:
  discovery would only re-litigate decisions the sources already made.
- A test-specifiable feature — use `tdd` directly.
- A bug-fix iteration — use `debug` directly.
- A tidy iteration — use `audit` directly.
- A trivial mechanical edit — per the project's CLAUDE.md carve-out.

**Do not skip `brainstorm`** when the design is genuinely open:

- A request framed as "I have a clear vision, just plan it" whose vision still
  hides an unresolved fork.
- A cycle where a load-bearing decision is not yet made.

The discriminator is the design line: if the sources resolve every
load-bearing decision, the work belongs to `specify`; if writing the spec
would force you to *pick* one, discovery is what resolves it, and that is
`brainstorm`.

## The Iron Law

```
ENUMERATE EVERY LOAD-BEARING DESIGN FORK BEFORE POPULATING ANYTHING — THIS
  ENUMERATION IS ALSO THE ORCHESTRATOR'S OWN INDEPENDENT SIGNAL, USED LATER TO
  CROSS-CHECK THE SWARM.
A FORK THE SWARM SETTLES ON A *CITED SHARED GROUND* WAS DERIVABLE -> PRESENT IT
  DECIDED (USER VETOES), AND RECORD THE GROUND. A FORK THE SWARM SPLITS ON, OR
  AGREES ON WITH *NO CITABLE GROUND* (UNGROUNDED-CONSENSUS), IS A DIRECTION
  FORK -> THE USER'S CALL. THE LINE IS GROUNDED-DERIVABILITY VS PREFERENCE,
  NOT SMALL VS LARGE, AND NOT BARE AGREEMENT.
A FORK THE ORCHESTRATOR'S OWN ENUMERATION FLAGGED OPEN BUT THE SWARM CLOSED IS
  SURFACED TO THE USER ANYWAY — THE SWARM NEVER ERASES A FORK THE ORCHESTRATOR
  INDEPENDENTLY HELD OPEN.
THE DECIDING WORK IS NEVER SKIPPED. A DESIGN PRESENTED WITHOUT THE FORK
  ENUMERATION + SWARM + TRIAGE DONE IS THE RUBBER-STAMP BETRAYAL, NOT DISCOVERY.
DESIGN DIRECTION IS SET HERE BY THE USER — NEVER DELEGATED TO THE SWARM, NEVER
  TO `specify`.
```

Every clause is non-negotiable. The swarm is *evidence*, not an oracle: it
populates the space and exposes where stances split, but the convergent-vs-
direction verdict is the orchestrator's derivability judgement (the same one
`specify` Step 1.5 applies), and bare agreement among same-model stances is
never that judgement — only agreement on a citable ground is.

## The Process

### Step 1 — Explore project context

Before enumerating anything:

- `git log -5 --format=full` for the full bodies of the most recent iter /
  audit commits — current state of the project.
- If the project has a design ledger (its CLAUDE.md project facts name it),
  walk to the relevant contracts for the invariants the new cycle might touch.
- When reading any file under the project's design models, note its `status` /
  `validated-against` frontmatter if present: `status: aspirational` means its
  code is a target, not verified fact. Track which content is flagged for
  lift-time validation when `specify` writes the spec.
- `git log --oneline -20` for the chronological scan.
- Identify scope: is this one cycle, or does it need to be decomposed into
  sub-cycles first? If multi-subsystem, decompose.

### Step 2 — Enumerate the load-bearing forks

List the **load-bearing design forks** the cycle forces — the choices that,
decided differently, would change what ships — exactly as the clarifying
questions you would otherwise have put to the user. Cover at least:

- **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?

For each fork, privately note whether *you* think it is derivable or genuinely
open. This enumeration is the swarm's input **and** your own independent
signal: a fork you flagged open that the swarm later closes is surfaced to the
user anyway (the Iron Law cross-check). Do not interview the user here — no
serial questions.

### Step 2.5 — Fire-check (skip the swarm when it would be ceremony)

The swarm is justified only when there are **multiple non-trivial forks whose
derivability is genuinely uncertain** *and* there is enough checked-in ground
to answer them honestly. Skip it, and resolve inline, when:

- **Too few forks.** Zero or one real fork — answer it directly (a single
  derivable fork is decided and noted; a single open one is one question to
  the user). Spinning up a swarm for one fork is more machinery than the
  ceremony it replaced.
- **Grounding floor not met.** No design ledger, a thin or absent glossary, an
  under-specified audience — a greenfield or new-territory project. With
  nothing to cite, every synthetic stance confabulates and "convergence" is
  100% hallucination wearing a quorum. Below this floor the swarm is NOT
  dispatched; fall back to a direct human interview (and under `/boss`, that is
  a bounce-back — see § Under `/boss`).

Record the skip reason in the cycle's notes / the run's reference issue. The
swarm is an optimization for context-rich mature projects, not an
unconditional default.

### Step 3 — Populate the space with the synthetic-user swarm

Dispatch the read-only `agents/synthetic-user.md` agent **in parallel, one per
stance, in a single turn** — the same ad-hoc fan-out brainstorm already uses
for `plan-recon` and `specify` uses for `spec-skeptic`. No Workflow wrapper: a
one-shot stateless fan-out has no re-loop, no ordering, and no in-code verdict
to enforce, so it is a direct dispatch, not an `implement-loop`-style script.

The roster is **fixed convention** (no per-project config knob; only the
*grounding* — the project's declared audience / ledger / glossary, reached via
standing reading — varies):

- **minimalist** — convention over config, the smallest change that ships.
- **power-user / composability** — capability, extension, what it unlocks.
- **maintainer / future-self** — invariants, drift cost, long-term carry.
- **skeptic** — does this need to exist at all (the feature-acceptance
  criterion incarnate).
- **off-ledger wildcard** — advocates the direction the project does *not*
  imply. Inherently ungrounded by design, so it can only ever surface a fork,
  never close one; it exists to keep the swarm from collapsing into
  status-quo unanimity.

Each stance answers the whole `fork_set` with a **mandatory per-answer source
citation or an honest `ungrounded:true`** (the agent's Iron Law). The swarm
ONLY answers the forks; it never authors approaches.

### Step 4 — Triage and present the populated space

This is the **one user stop** in interactive mode. Cluster the stances'
answers per fork and apply the derivability test — the same one `specify`
Step 1.5 uses, measured here against the swarm:

- **Converged on a cited shared ground → DECIDED.** Present it as decided with
  the ground shown; the user only vetoes. Record the ground.
- **Split, or converged with no citable ground (ungrounded-consensus) →
  DIRECTION FORK.** The user's call. Surface the conflicting positions (and
  the wildcard's off-ledger alternative where it raised one) as the things to
  weigh. Bare agreement among same-model stances is *not* a decision — demote
  it.
- **Cross-check.** Any fork your own Step-2 enumeration flagged open that the
  swarm closed is surfaced anyway, never auto-decided.

Then **author the 2-3 approaches** yourself — the orchestrator's job, never the
swarm's. They crystallise out of the populated space: the converged axes are
fixed; each genuine direction fork's conflicting answers *is* an approach the
user weighs. Lead with your recommended option and why; for each:

- **concrete code first, prose second.** The primary artefact is the actual
  program or invocation that should work under this approach, in the project's
  canonical authoring or consumer form. The implementation shape (changed
  struct / signature / match-arm, before → after) is secondary supporting
  detail, never a substitute for the user-facing code.
- substantive trade-offs (semantic fit, schema impact, performance,
  composability).
- effort observation (NOT effort as rationale — see the project's CLAUDE.md on
  design rationale ≠ implementation effort).

Present the conceptual design alongside — Architecture, Components, Data flow,
Error handling, Testing strategy — each scaled to complexity. This design is
conceptual: the concrete user-facing code and the before → after shapes are
materialised downstream when `specify` writes the spec and applies the
acceptance criterion. Your job here is to get the *design decision* right and
ratified, not to write the artefact.

If the populated space shows **every** candidate approach is bad, that is the
"problem is mis-framed" signal — STOP and escalate to the user, do not ratify a
known-bad shape. Three unsatisfying approaches mean the problem is wrong, not
that one must be picked.

### Step 5 — Deepen the forks the user opens

Deepening is **free chat** with the orchestrator by default — the user's
native mode, and the one place they have chosen to engage. A direction fork is
by definition one the swarm could not ground, so re-running the swarm on it
asks the machinery that already failed to converge to try again; do not make a
second swarm round the default. It is an **optional** tool the orchestrator MAY
reach for, scoped to one fork, only to populate *in-direction* sub-options once
the user has tilted toward a direction, or to rescue a fork that turns out to
be mis-framed — `spec-skeptic`-style, a tool reached for, not a gate.

**Capture the resolution.** Whatever the chat settles is folded into the
ratified design narrative handed to `specify`, and minuted on the run's
reference issue (the `specify` Step-1.5 reconciliation-comment / `boss`
decision-log discipline). The free-chat deliberation that used to evaporate now
lands in the pipeline.

### Step 6 — Hand off to `specify`

The terminal state of `brainstorm` is invoking `specify`. NO spec file is
written here; NO other skill is invoked; NO direct jump to `planner` or
`implement`.

Hand off carries the **ratified design narrative**, in-context (same
orchestrator context — no intermediate artefact):

- the approach chosen and why
- the constraints and invariants surfaced in the swarm + deepening
- the design sections the user ratified (Step 4)
- the **decided forks with their cited grounds**, and the **resolved direction
  forks with the user's choice** — so `specify`'s chain-entry (Step 1.5,
  "re-ground lightly … rather than re-deriving it") reads them as already
  settled instead of re-litigating them
- the iteration scope ("the first iteration covers section X+Y")

`specify` reads this narrative as its source, applies the acceptance criterion,
writes the spec, runs the parse and grounding-check gates, takes sign-off, and
hands off to `planner`. The production gates live there, not here.

## Under `/boss` (autonomous)

When the user is away, the swarm runs **autonomously** — the discovery is now
bounded and context-compacting (the orchestrator gets back a triaged populated
space, not a 10-round interview transcript), so a fresh `brainstorm` is no
longer a mandatory pre-dispatch bounce. The autonomous contract mirrors
`specify`'s bold-decide stance:

- **Decide the convergent forks.** A fork the swarm settles on a cited shared
  ground is decided autonomously and **recorded on the run's reference issue**
  with the ground (the `boss` § Direction-freedom decision-log discipline) —
  exactly as `specify` Step 1.5 records a derived fork.
- **Bounce only the divergent direction forks.** A genuine direction fork (split,
  or ungrounded-consensus, or one the Step-2 cross-check held open) is the
  user's call; there is no user present, so it routes to a **problem-state
  bounce** — a vetoable notify naming, in the user's terms, the design choice
  that needs them. The convergent decisions ride along; only the genuine forks
  stop the loop.
- **Grounding floor → bounce.** If Step 2.5's grounding floor is not met
  (greenfield, no ledger), the swarm cannot run honestly and the work needs a
  human interview — that remains a bounce-back, on grounding grounds, not on
  the retired "fresh brainstorm is too high-context" rationale.

See `../boss/SKILL.md` § Direction freedom (trigger 4) and the Entry-path
reflection for how this folds `brainstorm` into the autonomous cascade.

## Handoff Contract

| Direction | Carrier |
|-----------|---------|
| user → `brainstorm` | new cycle request with a genuinely open design |
| `brainstorm` → `synthetic-user` swarm (Step 3) | `fork_set` + one `stance` per dispatch + grounding pointers; read-only, parallel, no Workflow |
| `brainstorm` → user / reference issue (Step 4 / `/boss`) | the triaged populated space: decided forks + cited grounds, direction forks surfaced for the user's call |
| `brainstorm` → `specify` (Step 6) | ratified design narrative (approach, constraints, ratified sections, decided forks + grounds, resolved direction choices, iteration scope) — in-context; no spec file written |

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| "User says 'clear vision, just plan it' — skip the discovery" | "Clear vision" is a starting point, not a settled design. Enumerate the forks; the swarm will show which the vision actually resolves and which it papers over. The ones it papers over are the user's to settle. |
| "Present my own derived design without the swarm — I already know the answer" | Deriving one answer alone and presenting it polished is the single-guess rubber-stamp. The swarm's diversity is what surfaces the constraint you did not think to derive; the cross-check is what stops your own prior from erasing a fork. Run the swarm (above the fire-check floor) or you are shipping unfiltered intuition with extra steps. |
| "The swarm all agreed, so the fork is decided" | Only if they agreed on a *cited shared ground*. Same-model stances agree by shared prior all the time — that is ungrounded-consensus, and it is a direction fork for the user, not a decided one. Bare agreement is the false-convergence trap, not a verdict. |
| "There's a direction fork left — re-run the swarm on it to be thorough" | A direction fork is the one the swarm could not ground; re-swarming asks the same non-oracle the same unanswerable question at higher resolution, and the extra detail only makes the guess more persuasive. Deepen it in free chat with the user; a scoped re-swarm is optional and only for in-direction sub-options after the user has tilted. |
| "Three approaches in, none feel right — ship the least bad" | Three unsatisfying approaches usually means the problem is mis-framed. Stop, capture what fails about each, escalate to the user. End-of-day pressure is the worst signal to resolve a design fork. |
| "Spec exists from previous cycle, append to it" | The previous cycle's spec was retired at its close (see `../docs/conventions.md` § Lifecycle) — there is nothing to append to. New cycle = new spec file; mixing scopes makes drift review unreadable. |
| "Let the swarm author the approaches — it has the stances already" | The swarm answers forks; the orchestrator authors approaches. A finished design from the swarm delegates design DIRECTION to a fan-out — the same downstream-delegation sin the reform exists to prevent, just relocated from `specify` to the agents. |

## Red Flags — STOP

- "Skip the discovery" thoughts (any flavour) on a genuinely open design.
- Presenting a design without having enumerated the forks, run the swarm
  (above the fire-check floor), and triaged it.
- Treating bare swarm agreement as a decision — an ungrounded-consensus
  silently auto-decided instead of surfaced as the user's call.
- A fork your own Step-2 enumeration held open, quietly closed by the swarm and
  not surfaced (the cross-check skipped).
- Letting the swarm author the 2-3 approaches, or delegating any design
  *direction* to it.
- Re-running the swarm on a direction fork as the default deepening path
  instead of free chat with the user.
- Running the swarm below the grounding floor (greenfield, no ledger) and
  trusting its confabulated convergence.
- "The 2-3 approaches all suck, just pick one" — that is the mis-framed-problem
  escalation, not a forced pick.
- Inventing a design rationale that's actually about effort, not semantics.

## Cross-references

- **Agent dispatched:** `agents/synthetic-user.md` — the read-only synthetic
  design-stance respondent, dispatched as a parallel swarm in Step 3. A
  `spec-skeptic` sibling: a fixed read-only lens family that returns a finding,
  never a verdict.
- **Output target:** `../specify/SKILL.md` — the only valid next skill.
  `brainstorm` hands the ratified design to `specify`, which produces the spec
  and gates `planner`. There is no direct `brainstorm → planner` edge.
- **Shared derivability test:** `../specify/SKILL.md` Step 1.5 — the
  derivable-vs-pure-preference line `brainstorm` measures against the swarm is
  the same one `specify` applies to the sources; defined there, referenced here,
  so the two cannot drift.
- **Alternative entry path / bounce-back source:** `../tdd/SKILL.md` — a
  test-specifiable feature enters through `tdd` instead; `tdd` bounces back the
  moment the behaviour stops being test-specifiable. `../specify/SKILL.md`
  likewise bounces back here when the sources do not resolve a design fork.
- **Autonomous behaviour:** `../boss/SKILL.md` § Direction freedom (trigger 4)
  and the Entry-path reflection — how the autonomous swarm-brainstorm decides
  convergent forks and bounces only divergent ones.
- **Ad-hoc dispatch.** The orchestrator MAY also ad-hoc dispatch
  `../planner/agents/plan-recon.md` during Step 1 when the cycle enters code
  territory not recently read; ad-hoc, not part of the standard process.
- **Project feature-acceptance criterion:** declared in the project's
  `CLAUDE.md` — applied prospectively by `specify` (its Step 2), not here.