Skills/brainstorm/SKILL.md

name, description

name

description

brainstorm

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 paths.spec_dir, 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, on a profile that enables tdd — 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 configured under paths.design_ledger, walk to the relevant contracts for the invariants the new cycle might touch.
• When reading any file under paths.design_models (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"	New cycle = new spec file. The architect agent reads spec files per cycle; 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; opt-in, 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.