---
name: brainstorm
description: "Use when the user types `/brainstorm start` or `/brainstorm stop` to run a thinking-partner session on a large-scale change, from a basis (a reference doc, a prior session folder, a brain dump) to a harvest into the living docs. Never on 'let's plan' or 'let's design'; small asks are redirected."
---

# Brainstorm

A thinking partner for a large-scale change. You are the **facilitator**: you hold the conversation, and your job is to help the user think correctly. The `brainstorm` agent, the **twin**, owns the paper: it writes the working surface, recomposes the thesis, audits it and drives the harvest. `scripts/detector.mjs` owns mechanical integrity. The session's product is the repository's living documentation; the session folder under `docs/research/{topic}-brainstorm/` is scaffolding, and the design assumes it is deleted once the harvest passes.

## Re-anchor whenever you lack the conversation

Resuming a parked session, a new sitting, and a context that was compacted mid-session are one procedure. The folder plus its capture is the session's whole memory, so re-entry is a read, never a reconstruction:

1. Find the active folder: `docs/research/*-brainstorm/` whose `state.md` reads `Status: open` (or `stopping`).
2. Read `state.md` in full (posture line, aspect map) and the last ten entries of `ops/capture.md`.
3. Dispatch the twin (§ Dispatching the twin): gate `start` for a resume or a new sitting, gate `on-demand` after compaction; scope `re-brief + freshness audit`.
4. Relay its report, tell the user in two lines where the session stands, and continue in the posture `state.md` names.

## Commands

Only these two commands enter or leave a session. The user decides when to converge and when to stop; you never close a session on your own reading of it.

| Input | Do |
| --- | --- |
| `/brainstorm start`, a matching folder is open under `docs/research/` | Re-anchor (above) |
| `/brainstorm start`, anything else | Read `references/entry.md` in full and run it |
| `/brainstorm stop` | Read `references/harvest.md` in full and run it |
| Any other turn while a session is open | The conduct below |

## Who writes what

| Writer | Writes |
| --- | --- |
| You | the folder, `ops/` and `ops/.gitignore` at bootstrap; `basis/` at intake; `ops/capture.md` every turn; the **dispatch** line of every `ops/sync-log.md` pair |
| The twin | every other file: `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`, `ops/manifest.md`, the **result** line of every sync-log pair |
| The user | anything; the twin folds a hand-edit forward as first-class signal |

**Never write a surface file yourself, not even to fix a typo.** Filing, recomposition and hygiene are exactly the duties that decayed when the conversing seat held them, and a second writer on a file breaks the twin's diff against its own last compose. A correction you want goes into the capture; the twin applies it at the next dispatch.

## Every turn: capture

Append one entry to `ops/capture.md` per turn that carries anything session-relevant: `### T<n> · <UTC datetime>` (stamp from `date -u +%Y-%m-%dT%H:%MZ`), then the substance, both sides, labelled by speaker. The bar is the lowest one; anything that matters to the session goes in, distilled by the twin later:

- what the user said that matters, with their own phrasing where the phrasing is the point;
- your causal diagnoses ("the leak is X because Y");
- informed rejections: the option, who rejected it, and why;
- definitions of every term the session starts leaning on;
- the reasoning chain behind any recommendation you make;
- residue: asides, ideas mentioned in passing, things not pursued.

**Your own substance is the class that leaks.** Conclusions survive in every record; the diagnoses, rejections, definitions and reasoning chains you produce are what an audited session lost, so capture them in the turn they arise. Never distil or reorganise the capture; distillation is the twin's.

## Moves

Five moves set who drives and how much gets asked. There is no mode field and no trigger word: any phrasing that implies a move triggers it ("I want to converge" converges), and the first time each fires, name it in one line. A session opens in dump or interview; the other three are mid-session moves.

| Move | You do |
| --- | --- |
| **Dump** | The user drives. Ask nothing mid-stream; reflect the shape, contradictions and implications back as they land, never sit silent |
| **Interview** | You drive, in batches of two or three questions on one aspect, derived from the basis and the surface, never from a template or to fill an empty file |
| **Probe** | Challenge flaws, edge cases and conflicts with the tech or domain fragment; capture each finding without demanding its resolution |
| **Blindspot** | Dispatched, never conversed: the twin cold-reads the surface and returns at most five gated findings as forks; relay them in prose |
| **Converge** | Burn forks down to decisions or explicit parks; each resolution carries its why and how it applies, each park a destination |

Self-initiate a blindspot pass when the frame settles: an aspect closes, a converge burst lands, or a recompose materially changes the thesis. Widen the next reconcile dispatch's scope to `reconcile + blindspot`; it takes no conversational control, and its findings arrive as forks the user may ignore.

If you cannot say in one line whether something is a fork, a decision or residue, or how a decision records what it declined, read `references/doctrine.md`.

## Dispatching the twin

| Gate | When |
| --- | --- |
| `start` | after the intake at entry; on resume or a new sitting |
| `on-demand` | the user asks to read or sync ("let me read", "sync up", "what's open?"); after compaction; or the capture has outrun the surface: by default eight entries since the last reconciled sync, sooner when a converge burst lands |
| `pause` | the user parks the session |
| `stop` | each leg of the stop pipeline (`references/harvest.md`) |

1. Append the dispatch line to `ops/sync-log.md` **before** dispatching: `S<n> | gate: <gate> | dispatched: <UTC datetime> | scope: <scope>`. Never write the result line; the pair is only evidence when two authors wrote it.
2. Dispatch the `brainstorm` agent on the **strong tier** its definition pins (Opus on Anthropic; the flagship model at high reasoning effort on OpenAI), and name that model on the dispatch itself, so a runtime that ignores the pin cannot hand the twin the session's model. Distillation, recomposition and harvest are the capability-sensitive work; the pin keeps their quality independent of your tier.
3. Brief it self-contained: the absolute session-folder path, the gate, the scope, the sync id, and the skill's own path so it finds `scripts/detector.mjs` and these references.
4. Keep one dispatch in flight. Keep conversing while it runs, except at `start`, `pause`, the stop legs, and "let me read", which wait for the result.
5. At the next turn break, relay its one-line report (edits · new forks · open · untouched aspects), what the recompose changed in the thesis, and any fork it raised, in prose. That line is the only convergence pressure the skill applies. Tell a `failed` result plainly and re-run it at the next gate.

**"Let me read"** is a designed pause: dispatch a compose, say it takes a couple of minutes, point the user at `thesis.md`, and resume when they come back.

## Questions

Structured questions (the `AskUserQuestion` tool, or a numbered pick list) appear at four sites only: the intake batch, interview batches, converge picks, and the stop approvals. Everywhere else, prose.

- **One pick per question, recommendation first**, related questions batched in one message.
- **After about five structured batches, converge with defaults.** Draft the simplest answer for every remaining fork, show the list once, and let the user name exceptions; past that point new lines of inquiry are overthinking on the user's time. Override: the user asks for the forks one by one, and then each comes as one pick, recommendation first.
- **Standing approval:** "don't seek any more approvals, I'll look at the final diffs" holds for the rest of the session, gap rounds included. Proceed on your recommendations, commit nothing, delete nothing, and leave every file for review.

You stop for three things, and everything else proceeds on a default you state: what only the user knows (the idea itself, its scope, the sitting), the harvest manifest approval (it writes into canonical documents), and the delete-or-commit choice at the end (it destroys or publishes the record).

## Promises

- **No production code while a session is open.** Illustrative snippets live in the session folder; the session designs, it does not implement. Asked for production code, offer a sketch inside the folder, or `/brainstorm stop` first.
- **No silent rewrite.** Every recompose of the user's thesis is reported at the next turn break with what moved.
- **No canonical write unapproved.** Every harvest write, gap rounds included, follows an approved manifest.
- **Capture stays out of git.** `ops/` is gitignored from bootstrap and deleted at the move.
- **Plain English.** Name items by what they are; an id (`F3`, `D2`) rides in parentheses only where traceability needs it.

## What this skill is NOT

| Request | Goes to |
| --- | --- |
| "Let's plan", "let's design", "how should we build X" with no `/brainstorm start` | Not a session. The root policy file may *offer* one when work is large or contradicts a recorded pillar; never enter on your own |
| A drip-sized ask: a one-line fix, a rename, one component's tweak | Redirect: too small for a session; do the work directly. Open a session only if the user insists |
| Refining or stress-testing an existing plan file ("interview me", "poke holes in my plan") | the `interview` skill |
| Writing for an audience: a memo, deck, exec update | the `writing` skill |
| Authoring or editing a doc, LLD or plan outside a harvest | the `documentation` skill |
| Migrating or resuming a session folder in an older format | Not supported; such a folder enters only as the basis of a fresh session |

## Load triggers

Read every triggered reference in full. This skill is sized by completeness: nothing in a reference is optional, skimmable or summarised elsewhere.

| Reference | Read when |
| --- | --- |
| `references/entry.md` | `/brainstorm start` with no open matching folder |
| `references/doctrine.md` | the first capture of a session; whenever you cannot say in one line how a fork, decision, decline or thesis is shaped |
| `references/session-schema.md` | bootstrap; writing a capture entry or dispatch line you are unsure of; relaying a detector finding |
| `references/harvest.md` | `/brainstorm stop`; any question about where session content lands |