/brainstorm

name: brainstorm
description: "Explore an ambiguous idea with the user, settle scope and success criteria, and produce an independently reviewed design for wish."
category: lifecycle
mutates: documents

Brainstorm

Use when the problem, approach, or boundaries need decisions. Explore with the user; do not implement. Resume a related draft rather than starting another: the slug names `.genie/brainstorms/<slug>/`, whose `DRAFT.md` carries the state of every round.

The brainstorm is a saved workflow that runs one round per invocation, because a workflow cannot wait for a person: the owner answers between runs. The single source of truth is `.claude/workflows/brainstorm.js` in the genie repository's workflow catalog (see `.claude/workflows/README.md` there); this skill is its front door and carries no stage roster of its own. On a runtime that runs saved workflows, run the script at `<repository root>/.claude/workflows/brainstorm.js` when that file exists, otherwise `~/.claude/workflows/brainstorm.js` (delivered by `genie install` / `genie update`); give the runtime that explicit script path, never a bare name — both scopes carry these names and the order a name resolves in is undocumented. On a runtime that does not, or where neither file exists, follow "Without a workflow surface" below.

Invoke

Pass `{slug, request?, answers?, repo, tools: {ledger, evidence, reviewContract}, councilCeiling, repairBudget, model?, timestamp}` through args, every path absolute:

• `slug` is lowercase letters, digits and dashes; `request` is the idea in the owner's words; `repo` is the repository root; `timestamp` is the caller's clock, since the workflow has none; `model` pins every stage.
• `tools` resolve from this skill's own directory, never from the checkout, so a round runs from any repository: `ledger` is `references/round-ledger.mjs`, `evidence` is `references/design-review-evidence.mjs`, and `reviewContract` is `review/SKILL.md` in the skills directory that holds this one, the `review` skill installed beside it; a single-skill install has none, and the run ends `failed` naming the path. The design template stays at `references/design-template.md` beside the ledger, where the workflow finds it.
• `councilCeiling` is the value `genie config get budgets.maxCouncilsPerBrainstorm` prints and `repairBudget` the value `genie config get budgets.maxEscalationsPerGroup` prints, each passed as an integer, never as the printed string: the workflow treats anything that is not an integer as unset, so the string "0" would quietly raise an owner's ceiling of 0 to the default 1. When `genie` is absent or a read exits non-zero — an installed release older than the council key exits 1 on it — pass that value's schema default (ceiling 1, repair budget 2) and say so when you relay the result.

Each round

1. Run the script, then relay the WRS bar (`wrs.bar`), the plan as run and the `notes`. Whatever the state, run `genie wish report <runId> --append` with the run id the runtime reported, and relay its output: the run's tokens and time per stage, and one row in the machine-local ledger. Without `genie`, relay the run id and say the run's cost was not recorded. 2. Relay `questions` through the runtime's question harness, at most four per batch: each question's text, header, `multiSelect` flag, option descriptions and option labels exactly as returned, in the order returned, with no rephrasing and no translation. Ids and kinds stay outside the harness payload. 3. Map the answers back to ids by question order and invoke again with `answers: [{id, question, answer}]`: the id, the question text as the harness returned it, and the picked label (an array of labels for a multi-select) or the owner's own words verbatim. Leave out a question nobody answered; it stays Asked and comes back next round. 4. An empty `round`, with no question to relay, is a valid result: invoke again.

The per-question rule, verbatim: "An answer settles only the question it answers. Nothing rides along: a change the owner was not asked about, including any edit to something they already approved, goes in its own question. An approved decision is reopened only by a question that quotes it and shows old → new. Moves that add scrutiny may be taken and announced; moves that reduce what the owner sees, or change what they approved, wait for their answer."

`state` is one of:

• `round` — questions to relay, including a `council-approval` question (convene past the ceiling or not) or a `review-findings` question (repair again, I settle them, stop).
• `done` — DESIGN.md carries a verified SHIP stamp; the only next route is `wish`.
• `answered` — the owner ended with a recorded verdict and no design.
• `blocked` — a ledger refusal the owner must resolve, a BLOCKED review, the repair budget spent, or the owner's stop. Stop is permanent for the slug: resuming needs a new slug or a deliberate reopen.
• `failed` — a spine agent returned nothing, the ledger could not start, or the review contract is missing; `notConvened` names the agents.

Simplicity Gate

Choose the simplest complete design satisfying current user stories. Justify added state, caches, synchronization, configuration, or background work with a present requirement or measurement. Bound current data and separate history before introducing distribution machinery. Name concrete triggers for deferred complexity.

Planning index

`.genie/INDEX.md` is the single intake index. Reconcile a legacy `.genie/brainstorm.md` idempotently into it when encountered; do not maintain two indexes or duplicate entries. After each run, write this slug's entry with a link to `brainstorms/<slug>/`: Simmering while rounds run, Ready at `done`. An `answered`, `blocked` or `failed` run leaves the entry in Simmering with the state and its one-line reason beside it, since no reviewed design exists to make it Ready.

• Raw: captured idea.
• Simmering: draft with unresolved decisions.
• Ready: reviewed des