| name | brainstorm |
| description | This skill should be used when the user asks to "brainstorm", "explore ideas", "design a feature", "draft a spec", "capture a spec", or mentions ideation, requirements gathering, spec capture, or brainstorming depth/focus modes. Generates BRAINSTORM/SPEC documents from project + conversation context. Replaces the deprecated /craft:brainstorm command. For session-facet friction or pattern analysis across past sessions, use the brainstorm-insights skill instead. |
Brainstorm
ADHD-friendly ideation with two decision points (not four) and one escape
hatch (not a "switch depth" tree). Transforms a topic + project/git context
into a BRAINSTORM-<topic>-<date>.md or, with the save action, a
docs/specs/SPEC-<topic>-<date>.md.
Boundary With Adjacent Skills
| Skill | Role |
|---|
| brainstorm (this) | Generates BRAINSTORM/SPEC documents from topic + context |
brainstorm-insights | Aggregates session facet history into a friction/goals report — unrelated input, unrelated output, split out into its own concern (kept the directory name for path stability; only the Insights operation remains there) |
insights-apply | Consumes a brainstorm-insights report; writes suggestions into CLAUDE.md |
adhd-workflow | Session boundary ops (done, recap, next, focus, stuck, spec-review) |
project-planner | Project-scope planning after a SPEC exists |
plan-orchestrator / --orch flag | Multi-agent implementation planning — see "Going deeper" below |
Typical chain: brainstorm → SPEC → project-planner (breakdown) → adhd-workflow (spec-review/done).
Inputs
- Topic — explicit argument, or inferred from conversation /
.STATUS / git branch / recent commits.
- Depth (quick | default | deep) — controls question count. No "max" tier — see "Going deeper" below for why.
- Focus (feat | arch | ux | api | ui | ops) — shapes output sections.
- Action (optional
save) — capture as SPEC-<topic>-<date>.md.
Depth Budgets
| Depth | Time | Expert Questions |
|---|
| quick | < 1 min | 0 |
| default | < 5 min | 2 |
| deep | < 10 min | 6 |
Two decision points total per session: (1) depth+focus, asked together in
one AskUserQuestion call when not provided as arguments; (2) one optional
follow-up — "anything else before I generate this?" — offered once, after
the expert questions, regardless of depth. No per-depth escape-hatch menus,
no "switch depth mid-flow," no milestone re-prompting every N questions.
If the user wants more, they ask; don't build a state machine for it.
Flow
- Parse args / detect topic. If no topic, scan conversation,
.STATUS,
git branch, recent commits. 1 topic → use it; 2+ → one AskUserQuestion;
none → ask free-form.
- Pick depth + focus (if not provided as arguments) — single
AskUserQuestion call combining both, not two sequential menus.
- Context scan. Check for an existing SPEC or prior brainstorm on the
topic, project type,
.STATUS version, recent test failures. Pre-fill
answers where project state already answers a question.
- Expert questions. Per-depth count (0/2/6), from the question bank
(full text and selection logic).
8 categories × 2 questions = 16 base questions, plus 6 project-type
extensions (auto-detected via
utils/claude_md_detector.py). Use
AskUserQuestion.
Category override (-C / --categories)
Default category selection is focus-driven (see table below). Override with
-C <list> / --categories <list> (comma-separated, matching commands/brainstorm.md
frontmatter):
| Category | Covers |
|---|
req | requirements |
users | target users / audience |
scope | what's in / out of scope |
tech | technical approach, stack |
timeline | sequencing, milestones |
risks | risks, edge cases, failure modes |
existing | existing code/patterns to reuse or replace |
success | success criteria, how to know it's done |
all | every category above (default when -C omitted at deep) |
Default categories by focus:
| Focus | Default categories |
|---|
feat | req, users, scope, success |
arch | tech, risks, existing, scope |
api | tech, req, success |
ux | users, scope, success |
ops | tech, risks, timeline |
| (auto/unset) | req, users, tech, success |
Example: /brainstorm "caching" -C tech,risks limits expert questions to the technical and
risk categories regardless of focus.
- One follow-up offer. After the questions: "Anything else to add, or
ready to generate?" — single yes/no-shaped prompt, not a menu of depth
switches.
- Generate output. Focus-specific sections (user stories for
feat,
Mermaid diagram for arch, API endpoints for api, etc.). Save to
BRAINSTORM-<topic>-<date>.md.
- Spec capture (action=save, or prompted for feat/arch/api). Ask
user-story + acceptance criteria, render full SPEC template, write to
docs/specs/SPEC-<topic>-<date>.md.
- Going-deeper offer (optional, post-spec only) — see below.
Going Deeper: No In-Skill Agent Delegation
This skill does not spawn subagents itself. The pre-redesign version had
a "max" depth that launched 1-2 background agents directly from inside
brainstorm — duplicating what orchestrator-v2 already does (wave
checkpoints, file-based results, explicit model routing, AskUserQuestion
confirmation before spawning), but without those safeguards. It also
referenced agent type names that didn't exist (backend-architect,
product-strategist, etc.), which silently fell back to general-purpose
with no model pin — see agents/orchestrator-v2.md BEHAVIOR 2.
Instead: after a spec is captured (Step 7), offer to hand off to the
orchestrator via the existing --orch flag / plan-orchestrator skill /
/craft:plan <spec-path>. One delegation mechanism, already
hardened, instead of two.
Mandatory Interactive Steps
Even when all arguments are provided as flags, the per-depth expert-question
count (0/2/6) is never skipped. Skipping silently is a known regression
pattern. The depth/focus menu may be skipped when args supply them — the
questions themselves may not.
Removed: Per-Invocation Question-Count Override
The pre-redesign version supported colon notation (d:5, m:12, q:0) to override the
per-depth expert-question count on a single invocation. This is intentionally not carried
forward — the fixed per-depth counts (0/2/6) are part of the same two-decision-point
simplification described above ("Going Deeper"); a per-call override reintroduces the kind of
escape-hatch menu this redesign removed. If a specific topic genuinely needs more than 6
expert questions, run /brainstorm at deep, then use the "anything else before I generate
this?" follow-up offer (Flow step 5) to add more — don't request a count override.
Outputs
BRAINSTORM-<topic>-<date>.md (always — even when also saving a spec).docs/specs/SPEC-<topic>-<date>.md (when save action selected).- Terminal summary with paths and suggested next command.
Test-Plan Scaffolding (default-on)
When this skill emits a BRAINSTORM or SPEC artifact, it also emits a
test-plan scaffold by default. Pass --no-tests to suppress the section.
Tier-inference rule
Infer tiers from the shape of the artifact/change being scoped:
| Change shape | Tiers to emit |
|---|
| Flag / frontmatter / prose only | e2e + dogfood |
| + new parser or script | + unit |
| + cross-command data flow | + integration |
| + external dependency change | + dependency |
| + new command / skill / agent | + count-cascade dogfood |
Unselected tiers print as N/A — <reason> (never empty stubs).
Emission rules
- Emit test stubs red-first (failing placeholder, not passing no-op).
- Each stub carries
# TODO(author): delete if not contract-bearing until the author confirms the contract.
- Scaffold templates live in
../brainstorm-insights/references/scaffold-templates.md
(shared with orchestrate) — point to that file, do not duplicate templates inline.
--yes non-suppression
--yes auto-accepts prompts only; the test-plan and Documentation sections
are content and are still emitted under --yes. Only --no-tests /
--no-docs remove them.
Documentation Scaffolding (default-on)
When this skill emits a BRAINSTORM or SPEC artifact, it also emits a
Documentation section by default. Pass --no-docs to suppress the section.
Which docs to emit
Derive which documentation artifacts are needed by running the existing
doc-scorer rubric from skills/orchestration/references/doc-impact-rubric.md (threshold ≥3). Do not
invent a new rubric — reuse the scorer as the single source of truth. For
each doc type the scorer evaluates (guide, refcard, demo, mermaid),
pre-check ([x]) boxes that meet the threshold, mark the rest
N/A — score <N>.
Count-cascade exclusion
Auto-docs emission touches only semantic docs — CHANGELOG [Unreleased]
mirror, guide/refcard/tutorial prose. It never touches version or count
lines; those are excluded and stay in bump-version.sh.
Related Skills
brainstorm-insights — friction/goals reporting from session history (was bundled with this skill; now separate, directory name kept for path stability).project-planner — breakdown after a SPEC exists.plan-orchestrator / --orch — multi-agent implementation, post-spec.
