Skills/brainstorm/SKILL.md

---
name: brainstorm
description: Use when a new cycle is starting and the design is NOT yet settled — gathers requirements, explores 2-3 approaches with trade-offs, presents a sectioned design with user approval, then hands the ratified design to the specify skill to produce the spec. 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 spec generator

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

## Overview

Discovery is where the orchestrator does the *deciding* work —
surfacing requirements, exploring approaches, and ratifying a design
with the user. It is the front-end that resolves 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 mode the orchestrator discipline exists
to prevent.

`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 user sign-off. When the design is *already*
settled in the sources, `brainstorm` is skipped entirely and the work
enters through `specify` directly.

## When to Use / Skipping

Triggers:

- A new cycle is starting (e.g. user proposes a new feature
  area, a new subsystem, or a major refactor of an existing
  one).
- A cycle-scope spec is missing for an existing line of
  work and one is needed retroactively.

**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 user 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 Process

### Step 1 — Explore project context

Before asking any clarifying questions:

- `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, if it has
  them, or the ledger's "model" rows, note its `status` /
  `validated-against` frontmatter if present: `status:
  aspirational` means its code is a target, not verified fact.
  Track which content you may lift from such a source — it 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 — 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)
- **concrete code first, prose second.** The *primary*
  artefact is the actual program or invocation that should
  work under this approach — written in the project's
  canonical authoring or consumer form. Show it. The
  implementation shape (changed struct / signature / match-
  arm, before → after) is *secondary supporting* detail —
  "also useful, not the point" — include it but never let it
  stand in for the concrete user-facing code. "The approach
  extends the struct with a field" is not an approach; the
  user-facing program it makes work (or correctly reject) is.
- 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)

Wait for user choice before proceeding.

### Step 4 — 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

The design you present here is conceptual — the architecture,
components, data flow, error handling, and testing strategy the cycle
commits to. The concrete user-facing code and the before → after
implementation shapes are produced downstream, when `specify`
materialises this ratified design into the spec (and applies the
acceptance criterion against that worked code). Your job here is to get
the *design decision* right and ratified, not to write the artefact.

Ask after each section whether it looks right. Be ready to
revisit earlier sections if a later one surfaces a
contradiction.

### Step 5 — 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 Q&A
- the design sections the user ratified (Step 4)
- 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 user sign-off, and hands off to `planner`.
The production gates live there, not here.

## Handoff Contract

| Direction | Carrier |
|-----------|---------|
| user → `brainstorm` | new cycle request with a genuinely open design |
| `brainstorm` → `specify` (Step 5) | ratified design narrative (approach, constraints, ratified sections, iteration scope) — in-context; no spec file written |

## 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 the project carries. Write the spec; frame it as "load-bearing decisions this idea forces on us". |
| "Cycle is small, two iterations, no spec needed" | Iteration count isn't the metric — feature surface is. A two-iter feature touching design-ledger 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, capture the three approaches and what fails about each in the spec's design notes (or escalate to the user), 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 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; the architect reads one cycle's spec at a time, and 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 the design ledger. Escalate to the 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"
- Inventing a design rationale that's actually about effort,
  not semantics

## Cross-references

- **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 any more.
- **Alternative entry path / bounce-back source:** `../tdd/SKILL.md` —
  a test-specifiable feature enters through `tdd` instead of here;
  `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.
- **Ad-hoc dispatch.** The orchestrator MAY 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.