The brainstorming phase is the mandatory first stage of any development workflow in Superpowers. It enforces a design-before-implementation discipline by requiring user approval of a complete design specification before any code is written, scaffolding is created, or implementation skills are invoked.
This page documents the brainstorming skill workflow, its enforcement mechanisms, and how it integrates with the overall development pipeline. For the complete workflow sequence, see Complete Workflow Pipeline. For creating implementation plans after design approval, see Writing Implementation Plans.
Sources: skills/brainstorming/SKILL.md1-97 RELEASE-NOTES.md9-17
The brainstorming skill implements a hard gate that blocks all implementation activity until design approval:
<HARD-GATE>
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.
</HARD-GATE>
This gate prevents the following actions until design approval:
frontend-design, mcp-builder, etc.)The only skill that may be invoked after brainstorming is writing-plans, which creates the task breakdown for the approved design.
Sources: skills/brainstorming/SKILL.md14-16 RELEASE-NOTES.md13-14
The skill enforces a checklist of six sequential steps. Each step must be completed before proceeding to the next:
| Step | Activity | Output |
|---|---|---|
| 1 | Explore project context | Understanding of current state (files, docs, commits) |
| 2 | Ask clarifying questions | Refined requirements (purpose, constraints, success criteria) |
| 3 | Propose 2-3 approaches | Options with trade-offs and recommendation |
| 4 | Present design sections | Validated design with user approval |
| 5 | Write design doc | docs/plans/YYYY-MM-DD-<topic>-design.md committed to git |
| 6 | Transition to implementation | Invoke writing-plans skill |
The agent must create a TodoWrite task for each checklist item and complete them in order. This provides tracking and prevents step-skipping.
Sources: skills/brainstorming/SKILL.md24-31 RELEASE-NOTES.md14
Sources: skills/brainstorming/SKILL.md35-53
The using-superpowers skill includes an intercept for Claude Code's native plan mode. When the platform is about to enter plan mode, the skill flow checks whether brainstorming has occurred. If not, it routes through the brainstorming skill instead, preventing bypass of the design phase.
Sources: skills/using-superpowers/SKILL.md27-43 RELEASE-NOTES.md19-21
Design documents are written to:
docs/plans/YYYY-MM-DD-<topic>-design.md
The -design.md suffix distinguishes design documents from implementation plans, which use the pattern YYYY-MM-DD-<feature-name>.md. Both are stored in the docs/plans/ directory.
The design document covers:
| Section | Purpose | Scope |
|---|---|---|
| Architecture | High-level structure and component organization | Scaled to complexity (few sentences to 200-300 words) |
| Components | Individual modules and their responsibilities | Detailed for complex sections, brief for simple ones |
| Data Flow | How information moves through the system | Diagrams or prose as appropriate |
| Error Handling | How failures are detected and recovered | Strategies and patterns |
| Testing | Verification approach and test categories | Test-driven requirements |
Each section is presented incrementally and validated with the user before proceeding. Section size scales to complexity: a simple component gets a few sentences, a complex interaction gets 200-300 words.
Sources: skills/brainstorming/SKILL.md71-76 skills/brainstorming/SKILL.md80-84 RELEASE-NOTES.md17
The design is presented in sections, with user approval requested after each section:
This incremental approach prevents large-scale rework and ensures alignment throughout the design process.
Sources: skills/brainstorming/SKILL.md71-76
During the clarification phase, the skill specifies questioning patterns:
Questions focus on understanding purpose, constraints, and success criteria before proposing solutions.
Sources: skills/brainstorming/SKILL.md59-64
The brainstorming skill has exactly one valid terminal state:
Invoke writing-plans skill
The process flow diagram explicitly shows this as the only transition after design approval. The skill documentation states:
The terminal state is invoking writing-plans. Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
This creates a hard boundary preventing agents from jumping directly to implementation tooling.
Sources: skills/brainstorming/SKILL.md55 skills/brainstorming/SKILL.md86-87
skills/brainstorming/SKILL.md:86-87
The writing-plans skill reference is not prefixed with superpowers: because skill names are resolved by the skill discovery system, which handles namespace automatically. See Skills Discovery and Resolution for details.
Sources: skills/brainstorming/SKILL.md86-87
The most common attempt to bypass brainstorming is the belief that simple projects don't need design work. The skill explicitly counters this:
Every project goes through this process. A todo list, a single-function utility,
a config change — all of them. "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.
The v4.3.0 release specifically addressed models skipping the design phase or collapsing the process into a single text block. The enforcement mechanisms added:
| Mechanism | Implementation | Purpose |
|---|---|---|
<HARD-GATE> tags | XML-style emphasis blocks | Creates visually distinct barrier |
| Mandatory checklist | 6 enumerated steps | Prevents process collapse |
| Anti-pattern callout | Explicit section | Pre-empts specific rationalization |
| GraphViz process flow | DOT diagram | Shows only valid transitions |
| Terminal state constraint | Single exit to writing-plans | Blocks implementation skill shortcuts |
Sources: RELEASE-NOTES.md9-17 skills/brainstorming/SKILL.md18-20
| Principle | Implementation | Rationale |
|---|---|---|
| One question at a time | Sequential questioning loop | Prevents overwhelm, enables focus |
| Multiple choice preferred | Offer options when possible | Easier to answer than open-ended |
| YAGNI ruthlessly | Remove unnecessary features | Minimizes complexity and scope |
| Explore alternatives | 2-3 approaches required | Prevents premature convergence |
| Incremental validation | Section-by-section approval | Catches misalignment early |
| Flexible iteration | Allow clarification backtracking | Accommodates evolving understanding |
Sources: skills/brainstorming/SKILL.md89-96
The brainstorming skill is invoked:
using-superpowers detects implementation intent without prior designThe skill description uses imperative language to strengthen triggering:
You MUST use this before any creative work - creating features, building
components, adding functionality, or modifying behavior.
Sources: skills/brainstorming/SKILL.md3 RELEASE-NOTES.md260-262
The v4.3.0 release marked a shift from describing the workflow to enforcing it through structural mechanisms:
Before v4.3.0:
After v4.3.0:
<HARD-GATE> tags create explicit barriersThe release notes state: "Models were skipping the design phase and jumping straight to implementation skills like frontend-design, or collapsing the entire brainstorming process into a single text block."
Sources: RELEASE-NOTES.md9-17
Added in v4.3.0, the using-superpowers workflow graph includes an intercept for Claude Code's native plan mode:
"About to EnterPlanMode?" -> "Already brainstormed?";
"Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
This ensures that if the model attempts to enter native planning mode without having gone through brainstorming, it is redirected to the brainstorming skill first. Native plan mode is never entered directly.
Sources: RELEASE-NOTES.md19-21 skills/using-superpowers/SKILL.md30-32
The brainstorming skill is defined at:
skills/brainstorming/SKILL.md
Key sections:
The skill is referenced in:
Evolution documented in:
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.