# Brainstorm

> 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.

- Skill: `data-wise/brainstorm` (Agent Skill)
- Install (CLI): `npx skillmds@latest add data-wise/brainstorm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/data-wise/brainstorm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Data-Wise (https://skillmd.com/u/data-wise)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/data-wise/brainstorm

---


# 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

1. **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.
2. **Pick depth + focus** (if not provided as arguments) — single
   `AskUserQuestion` call combining both, not two sequential menus.
3. **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.
4. **Expert questions.** Per-depth count (0/2/6), from the question bank
   ([full text and selection logic](../../../docs/specs/_archive/SPEC-brainstorm-question-bank.md)).
   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.

5. **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.
6. **Generate output.** Focus-specific sections (user stories for `feat`,
   Mermaid diagram for `arch`, API endpoints for `api`, etc.). Save to
   `BRAINSTORM-<topic>-<date>.md`.
7. **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`.
8. **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`](../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`](../../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.