This page is the full reference for the brainstorming skill (skills/brainstorming/SKILL.md), which governs how agents explore and design work before writing any code. It covers invocation rules, the sequential checklist, key principles, anti-patterns, and output conventions.
For the broader workflow context in which brainstorming sits — including how it connects to writing-plans, subagent-driven-development, and branch finishing — see §6.1. For the meta-skill rule that mandates checking for applicable skills before any action (including before brainstorming), see §7.1.
The brainstorming skill converts a raw idea into a documented design through structured collaborative dialogue. It enforces a HARD-GATE that prohibits any implementation action until the user has explicitly approved a design.
The skill lives at skills/brainstorming/SKILL.md and is accessible via the superpowers:brainstorming namespace. It is also exposed as a Claude Code command at commands/brainstorm.md which instructs the agent to invoke the skill and follow it exactly.
| Platform | How to invoke |
|---|---|
| Claude Code | /brainstorm command, or Skill tool with superpowers:brainstorming |
| Cursor | superpowers:brainstorming via skill tool |
| OpenCode | @superpowers:brainstorming mention |
| Codex | Automatic on name/description match, or explicit request |
The commands/brainstorm.md command file sets disable-model-invocation: true (commands/brainstorm.md1-7), meaning the command body itself does nothing except invoke the skill — all logic lives in the skill file.
Sources: commands/brainstorm.md1-7 skills/brainstorming/SKILL.md1-4
The most important enforcement mechanism in this skill is the <HARD-GATE> block:
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to every project regardless of perceived simplicity.
This gate is not conditional. It cannot be bypassed by arguments that the task is trivial.
Sources: skills/brainstorming/SKILL.md14-17
The skill explicitly names and rejects the most common rationalization for skipping design:
"Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
This mirrors the broader Red Flags table in using-superpowers (§7.1), which categorizes such rationalizations as signals that a rule is being avoided rather than genuinely evaluated.
Sources: skills/brainstorming/SKILL.md18-21
The skill mandates that the agent create a tracked task for each step and complete them in order. No step may be skipped.
| # | Step | Key Constraint |
|---|---|---|
| 1 | Explore project context | Check files, docs, recent commits before asking anything |
| 2 | Ask clarifying questions | One question per message; prefer multiple-choice |
| 3 | Propose 2–3 approaches | Include trade-offs and a stated recommendation |
| 4 | Present design | Section-by-section, get approval after each section |
| 5 | Write design doc | Save to docs/plans/YYYY-MM-DD-<topic>-design.md, commit |
| 6 | Transition to implementation | Invoke writing-plans skill — no other skill permitted |
Each checklist item becomes a TodoWrite task. This is the same pattern described in §3.2: the agent converts skill checklists into trackable to-do items.
Sources: skills/brainstorming/SKILL.md23-31
Brainstorming skill control flow
Sources: skills/brainstorming/SKILL.md35-55
Code entities involved in brainstorming invocation
Sources: commands/brainstorm.md1-7 skills/brainstorming/SKILL.md54-55 skills/using-superpowers/SKILL.md1-10
Before asking a single question, the agent reads the current project state: directory structure, documentation, and recent git history. This prevents asking questions already answered by the codebase.
| Field | Value |
|---|---|
| Location | docs/plans/ |
| Naming convention | YYYY-MM-DD-<topic>-design.md |
| Git | Committed after writing |
| Style | Use elements-of-style:writing-clearly-and-concisely if available |
writing-plansThe only permitted next skill is writing-plans. The skill file explicitly prohibits invoking frontend-design, mcp-builder, or any other implementation skill at this stage.
The terminal state is invoking writing-plans. skills/brainstorming/SKILL.md55
Sources: skills/brainstorming/SKILL.md57-88
| Principle | Meaning |
|---|---|
| One question at a time | Multiple questions in one message overwhelm; split them across turns |
| Multiple choice preferred | Reduces cognitive load; open-ended only when necessary |
| YAGNI ruthlessly | Remove unnecessary features from all designs before they reach implementation |
| Explore alternatives | Always 2–3 approaches; never present a single option as the only path |
| Incremental validation | Present design section by section, get approval at each step |
| Be flexible | If something doesn't make sense after approval, go back and clarify |
Sources: skills/brainstorming/SKILL.md89-96
Brainstorming is a process skill, not an implementation skill. Its role is determining what to build and how to structure it — not building it. See §7.1 for the skill priority order that places process skills before implementation skills.
The checklist-driven format also distinguishes it from free-form discussion: every step is tracked, every approval is explicit, and the design artifact is committed before any code is written.
Sources: skills/using-superpowers/SKILL.md29-43 skills/brainstorming/SKILL.md54-55
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.