brainstorming

Brainstorm ideas into designs

Help turn ideas into fully formed designs and specifications through natural collaborative dialogue.

First understand the current project context, then ask one question at a time to refine the idea. Once you understand what to build, present the design and get user approval.

Anti-pattern: "This is too simple to need a design"

Every project goes through this process. To-do lists, single-feature tools, configuration changes, all the same. "Simple" projects are most prone to causing the most waste due to unexamined assumptions. The design can be very short (a few sentences for truly simple projects), but you must present it and get approval.

Checklist

You must create a task for each of the following items and complete them in order:

Explore project context — check files, documentation, recent commits
Provide visual companion(if the topic involves visual questions) — this must be a separate message and cannot be combined with clarifying questions. See the Visual Companion section below.
Ask clarifying questions — one at a time, to understand purpose/constraints/success criteria
Propose 2-3 approaches — including trade-offs and your recommendation
Present the design — present it in sections by complexity, getting user approval after each section
Write the design document — save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commit
Spec self-review — quickly check inline for placeholders, contradictions, ambiguities, scope (see below)
User reviews the written spec — ask the user to review the spec file before continuing
Transition to implementation — invoke the writing-plans skill to create an implementation plan

Process

digraph brainstorming {
    "Explore project context" [shape=box];
    "Visual questions ahead?" [shape=diamond];
    "Offer Visual Companion\n(own message, no other content)" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    "Write design doc" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "User reviews spec?";
    "User reviews spec?" -> "Write design doc" [label="changes requested"];
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}

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.

Specific process

Understand the idea:

First look at the current project state (files, documentation, recent commits)
Before asking detailed questions, first assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), point this out immediately. Do not spend questions refining the details of a project that should first be broken down.
If the project is too large to cover with a single spec, help the user break it into sub-projects: which are the independent parts, how do they relate, and in what order should they be built? Then brainstorm the first sub-project following the normal design process. Each sub-project has its own spec → plan → implementation cycle.
For projects of appropriate scope, ask one question at a time to refine the idea
Prefer multiple-choice questions whenever possible, but open-ended questions are also fine
Ask only one question per message - if a topic needs more exploration, break it into multiple questions
Focus on understanding: purpose, constraints, success criteria

Explore approaches:

Propose 2-3 different approaches and their trade-offs
Present options in a conversational way, along with your recommendation and reasoning
First give the option you recommend and explain why

Present the design:

Once you believe you understand what is to be built, present the design
Adjust the length of each section according to complexity: a few sentences for straightforward content, up to 200-300 words for content with nuances
After each section, ask whether it looks correct so far
Cover: architecture, components, data flow, error handling, testing
If something does not make sense, be ready to go back and clarify

Design for isolation and clarity:

Break the system into smaller units, each with a clear purpose, communicating through well-defined interfaces, and able to be understood and tested independently
For each unit, you should be able to answer: what does it do, how is it used, what does it depend on?
Can someone understand what a unit does without reading its internal implementation? Can you change the internal implementation without breaking consumers? If not, the boundaries still need adjustment.
Smaller units with clear boundaries are also easier for you to work with - reasoning is better when you can fit the code into context at once; edits are more reliable when files are more focused. A file growing larger usually means it is doing too much.

Working in an existing codebase:

Explore the current structure before proposing changes. Follow existing patterns.
If existing code has flaws that will affect the work (for example, files that are too large, unclear boundaries, tangled responsibilities), incorporate targeted improvements into the design - just as a good developer would improve the code they are working on.
Do not propose unrelated refactoring. Focus on what serves the current goal.

After the design

Documentation:

Write the validated design (spec) to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
- (the user's preference for the spec location overrides this default)
If available, use the elements-of-style:writing-clearly-and-concisely skill
Commit the design document to git

Spec self-review: After writing the spec document, review it with fresh eyes:

Placeholder scan: Are there any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
Internal consistency: Do any sections contradict each other? Does the architecture match the feature description?
Scope check: Is it focused enough to go into a single implementation plan, or does it need to be broken down?
Ambiguity check: Could any requirement be interpreted in two different ways? If so, choose one and state it explicitly.

Fix all issues inline. No need to re-review — just fix and continue.

User review gate: After the spec review loop passes, ask the user to review the written spec before continuing:

"The spec has been written and committed to <path>. Please review it and tell me whether any changes are needed before we start writing the implementation plan."

Wait for the user's reply. If the user asks for changes, make the changes and rerun the spec review loop. Continue only after the user approves.

Implementation:

Invoke the writing-plans skill to create a detailed implementation plan
Do not invoke any other skills. writing-plans is the next step.

Core principles

One question at a time - Don't overwhelm the other person with multiple questions
Prefer multiple-choice questions - Easier to answer than open-ended questions when feasible
Strict YAGNI - Remove unnecessary features from all designs
Explore alternatives - Always propose 2-3 options before finalizing
Incremental validation - Show the design and get approval before continuing
Stay flexible - When something doesn't make sense, go back and clarify

Visual Companion

A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. It is a tool, not a mode. Accepting the companion means it can be used for problems that benefit from visual presentation; it does not mean every problem has to be handled through the browser.

Offer the companion: When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once first and get consent:

"Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visual materials as we go. This feature is still new and may use a lot of tokens. Want to try it? (This requires opening a local URL.)"

This offer must be a standalone message. Do not combine it with clarifying questions, context summaries, or anything else. The message should contain only the offer above, nothing else. Wait for the user's reply before continuing. If the user declines, continue brainstorming in plain text.

Per-question decision: Even if the user accepts, decide for each question whether to use the browser or the terminal. Criteria:Would the user understand it more easily by seeing it than by reading text?

Use the browser Show visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
Use the terminal Handle text content — requirements questions, concept choices, trade-off lists, A/B/C/D text options, scope decisions

A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout is better?" is a visual question — use the browser.

If the user agrees to use the companion, read the detailed guide before continuing: skills/brainstorming/visual-companion.md