brainstorming skill activates before any creative work: creating features, building components, adding functionality, or modifying behavior. Its job is to turn a rough idea into a fully formed, user-approved design document — and to do nothing else until that document exists.
Anti-pattern: “This is too simple to need a design”
Every project goes through brainstorming. 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 before writing any code.The nine-step checklist
The agent creates a task for each item and completes them in order:Explore project context
Check files, docs, and recent commits to understand the current state before asking a single question. If the request spans multiple independent subsystems, flag it immediately and help decompose it into sub-projects — each with its own spec, plan, and implementation cycle.
Offer a visual companion
If the topic will involve visual questions (mockups, layouts, diagrams), offer the browser-based visual companion in its own message — not combined with any other content. If the user declines, continue with text-only brainstorming.
Ask clarifying questions
One question per message. Multiple-choice questions are preferred when possible. Focus on purpose, constraints, and success criteria. Do not ask the next question until the previous one is answered.
Propose 2–3 approaches
Present distinct approaches with trade-offs. Lead with your recommended option and explain why. Present this conversationally, not as a formal list.
Present the design in sections
Once you understand what you’re building, present the design section by section, scaled to complexity. Ask after each section whether it looks right so far. Cover architecture, components, data flow, error handling, and testing. Revise until the user approves.
Write the design document
Save the validated design to
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commit it to git.Spec self-review
After writing the spec, review it with fresh eyes:
- Placeholder scan: Any “TBD”, “TODO”, incomplete sections, or vague requirements? Fix them.
- Internal consistency: Do any sections contradict each other?
- Scope check: Is this focused enough for a single implementation plan?
- Ambiguity check: Could any requirement be interpreted two different ways? Pick one and make it explicit.
User reviews the spec
Ask the user to review the written spec before proceeding:
“Spec written and committed to <path>. Please review it and let me know if you want to make any changes before we start writing out the implementation plan.”
Wait for the response. If changes are requested, make them and re-run the spec review. Only proceed once the user approves.Key principles
| Principle | What it means in practice |
|---|---|
| One question at a time | Never ask two questions in the same message |
| Multiple choice preferred | Offer A/B/C options when you can, not open-ended questions |
| YAGNI ruthlessly | Remove unnecessary features from every design |
| Propose 2–3 approaches | Always explore alternatives before settling |
| Incremental validation | Present each design section, get approval, then continue |
| Design for isolation | Each unit has one clear purpose and a well-defined interface |
Design document location
CLAUDE.md or AGENTS.md.
What happens after brainstorming
The only valid next step iswriting-plans. The terminal state of this skill is invoking that skill with the approved design document as its input.
Next: Writing plans
Break the approved design into 2–5 minute implementation tasks with complete code and TDD steps.