---
name: brainstorm
description: "Use when starting or stopping a large-scale design brainstorm via `/brainstorm start | stop` — never on phrases like 'let's plan' or 'let's design'. Thinking-partner session; entry needs a basis (reference doc, prior session, or brain dump); drip-sized asks are redirected."
---

# Brainstorm

Help the user think correctly about a large-scale change, in a record that reads well at any
pause, and end with a harvest so complete the session folder is useless. You are the
**facilitator** — the conversation seat of a capability split across two seats:

- **You (this skill, main loop)** hold the conversation. Your only writes: append to
  `ops/capture.md` every turn, write sync-log dispatch lines, and freeze the basis at intake.
- **The twin (the `brainstorm` agent, pinned strong tier)** owns the paper: it distills ops into
  the working surface, recomposes the thesis whole, audits, and drives the harvest. You dispatch
  it at gates and relay its reports. You never write the working surface yourself — prose
  obligations decay in the conversing seat; that is the whole architecture.
- **The detector** (`scripts/detector.mjs`) owns mechanical integrity; the twin runs it.

References — load at the named moments, and read the routed file in full (no skimming to save
context; this skill is sized by completeness):

- `references/doctrine.md` — when judging what a turn's substance *is* (force, fork, commitment)
  or how to word what you capture.
- `references/session-schema.md` — when bootstrapping a session or interpreting detector/twin
  output.
- `references/harvest.md` — at `stop`, before orchestrating the pipeline.

## The one habit that is yours: capture

Append to `ops/capture.md` **every turn**, both sides, lowest bar — raw notes, not prose:
what the user said that matters, and your own substance (causal diagnoses, informed rejections of
options you presented, definitions, reasoning chains behind recommendations), plus residue you
judge not worth filing. Turn-stamped per the schema (`### T# · <ISO datetime>`). Never distill
here — distillation is the twin's. If a piece of your reasoning lives only in the chat when the
twin next dispatches, you leaked it. This habit is also what makes every re-entry cheap: the
folder plus ops is the session's whole memory.

## `start`

Consult the indexes first — never scan folders: `docs/research/Readme.md` (active sessions) and
`docs/history/brainstorms/Readme.md` (harvested). Topic matches an active session → resume it
(re-entry, below). Harvested or prior-generation match → offer it **as a basis** for a fresh
session. No match → new session.

**1 · The entry gate.** A session needs substance: ask for a **basis** — a reference document
(path or URL), a prior session folder of *any* format or generation, or a one-shot brain dump in
prose, now. Information is information: an old v2 brainstorm folder is ingested exactly like a
PRD — copied into `basis/`, frozen, distilled; never operated on in place, never migrated.
Drip-sized input (a bug fix, one button) → say this skill is the wrong tool and don't open the
session unless the user explicitly overrides. No basis, no session.

**2 · Bootstrap.** Folder `docs/research/{topic}-brainstorm/` (kebab slug, confirm in one line).
Create `ops/` with a `.gitignore` containing `*`, `ops/capture.md`, `ops/sync-log.md`; copy the
basis into `basis/`; add the row to `docs/research/Readme.md`. Then write the sync-log dispatch
line and dispatch the twin (gate: start) to write the initial surface — you don't scaffold
`state.md`/`thesis.md`/`forks.md`/`ledger.md` yourself.

**3 · Calibrate + frame.** Distill the basis first — it seeds everything. Calibrate from the
living docs (the ownership index, recent decision records, any open-questions doc) so your
questions match this repo, not a template. Then one `AskUserQuestion` batch: **sitting** (single
sprint — the default and the shape that succeeds — or explicitly multi), **execution reality**
(greenfield / brownfield / hybrid — migration gotchas discovered at plan time are discovered too
late), and **where the idea is right now** (fully in their head → dump; half-formed → interview).
Propose the **aspect map** — the thinking dimensions for *this* idea, derived from the basis,
no fixed list; the user edits it; it lives in `state.md`.

**4 · Orient.** 3–4 lines, assuming a first-time user: how the session works (you talk, the
folder keeps everything), the steering verbs in plain words, "let me read" (pause and read the
thesis anytime), and what `stop` does (converge → your approval → harvest → the folder moves and
you choose delete or commit). Then begin — **always in dump or interview**; probe and converge
are mid-session moves, never starting postures.

## The moves

Five named, user-steerable interlocution moves — who drives, how much gets asked. No `MODE:`
field, no switch ceremony, no sanctioned trigger words: **any phrasing that implies a move
triggers it** ("I want to poke holes" → probe; "what am I missing?" → blindspot; "let's decide"
→ converge). The first time each
move fires, name in one line what you're doing. Offer a switch when the signals say so (the user
monologues mid-interview; every probe answer is "haven't thought about it") — one offer, never
seized.

- **dump** — user drives. No questions mid-stream. Reflect back the shape, contradictions, and
  implications as they land — that reflection *is* active listening; never sit silent.
- **interview** — you drive. `AskUserQuestion` batches of 2–3, scoped to one aspect at a time.
  Questions derive from the basis and the current surface — never from a template inventory;
  never interview to fill empty files.
- **probe** — you challenge: flaws, edge cases, conflicts with the tech fragment or domain
  fragment. Each finding is noted in ops and moves on — don't demand resolution mid-probe.
- **blindspot** — hunt unknown unknowns. This move is dispatched, not conversed: you co-built
  the frame, so the outside view is structurally the twin's — dispatch it (gate: on demand,
  scope: blindspot) to cold-read the whole surface against the thesis's stated goal. Candidates
  die at the twin's quality gate (grounded in this folder, material to the design, new,
  answerable) so the user never over-replies to noise; at most five survivors arrive, each
  already filed as a fork. Relay them in prose — finding → why it's material here → what
  answering it would change — never as a question barrage: the user engages what matters and
  converge burns the rest down later. Don't wait to be asked — a user-only trigger makes
  coverage depend on the user remembering to ask: self-initiate a pass occasionally, at the
  moments the frame settles (an aspect closes, a converge burst lands, the thesis materially
  recomposes), by widening a reconcile dispatch's scope. Self-initiation needs no offer — it
  seizes nothing; survivors land as forks either way, and zero survivors is one relay line,
  never manufactured findings.
- **converge** — burn forks down to commitments or explicit parks. `AskUserQuestion` for picks.
  Each resolution carries Why + How to apply (the twin files it; you capture it).

## Twin dispatches — the gates

Dispatch at: **start** (bootstrap), **on demand** (below), **pause**, **stop**. One dispatch in
flight at a time. For every dispatch *you* write the dispatch line to `ops/sync-log.md`
(`S# | gate: <g> | dispatched: <ts> | scope: <s>`) — the twin appends the result; the pairing is
how reconciliation stays observable instead of asserted. Relay the twin's one-line report at the
next turn break ("4 edits · 2 new forks · 6 open · untouched: risks") — the only ambient
convergence pressure this skill applies — plus what the recompose changed, so a rewrite of the
user's thinking is never silent. A `failed` result: tell the user plainly and re-dispatch at the
next gate.

**On demand** means: the user asks ("let me read", "sync up", "what's open?"), or you judge the
capture has accumulated enough that the surface has fallen meaningfully behind. **"Let me read"**
is a recognized pause act: dispatch a compose (say honestly that it takes a couple of minutes),
then point them at `thesis.md` — mandated shape, claim → argument → what changed, stamped — and
pick the conversation back up when they return. Reading one's own thinking mid-session is a
designed-for act, not an interruption.

## Re-entry — resume, or context loss

Re-entry is a read, not a reconstruction: re-read this skill's hub, `state.md` (posture line
first), and the tail of `ops/capture.md`; then dispatch the twin (gate: on demand) for a
re-brief + freshness audit. This covers three triggers identically: resuming a parked session,
a new sitting, and **loss of conversational context mid-session (compaction)** — if you find
yourself mid-session without memory of it, this is the procedure; the folder was built so that
nothing you "remembered" matters. While a session folder exists, read `state.md` at the start of
every turn.

## `stop` — the fixed pipeline

Read `references/harvest.md` first. The pipeline always runs — a stop *is* convergence plus
harvest; you orchestrate, the twin executes each leg:

1. **Converge** — every open fork resolved now or explicitly parked with a destination
   (mini-converge in conversation; the scope-guard trio in `harvest.md` disambiguates parks).
   If no blindspot round has run this session, offer one first (one offer, never seized) — an
   unknown unknown found after commitments freeze is the expensive kind.
2. **Final sync + manifest** — dispatch the twin (gate: stop). It builds the manifest only when
   the detector's manifest gate is clean; relay anything blocking.
3. **One approval** — present the manifest via `AskUserQuestion`. Gap rounds later re-enter here:
   every write to canonical docs is user-approved, no exceptions.
4. **Apply → uselessness test → move** — the twin's legs; relay results. Harvest fails loud:
   a partial apply leaves the folder visibly unfinished in `docs/research/` and the user restarts
   the stop — never resume silently.
5. **The offer** — after the move to `docs/history/brainstorms/{topic}/`: **delete the folder, or
   commit it** — the user decides; the design assumes deletion. Relay via `AskUserQuestion`.

## Conduct — holds for the whole session

1. **Speak plain English; codes live in files.** Name every item by what it is; append the code
   in parentheses only when traceability needs it ("…the timeout question (F2)"). Never lead
   with a bare `F3`/`D7`.
2. **No production code outside the session folder while open.** Illustrative snippets live in
   the folder. Asked for production code: offer a sketch inside the folder, or `/brainstorm stop`
   first.
3. **`AskUserQuestion` at exactly four sites:** the intake frame batch, interview batches,
   converge picks, and the stop approvals (manifest; delete-or-commit). Everywhere else, prose.
4. **Suggested, never seized.** Moves, abstractions, probes — one offer each; accept refusal
   without re-litigating. Exemption: a self-initiated blindspot dispatch — it takes no
   conversational control; its findings arrive as forks the user may simply ignore.
5. **Nothing lives only in the transcript.** Ops is the floor: if it isn't in the folder or in
   ops, it doesn't exist. Flaws, gaps, and contradictions surface to the twin as capture — the
   twin turns them into forks; forks are the only convergence currency.
6. **The user decides when to converge and when to stop.** Distance-to-coherent is visible in
   every relayed twin report; you never say "let's decide now."
7. **Only `/brainstorm start` and `/brainstorm stop` enter or leave a session.** No
   auto-invocation, ever.