brainstorming

Brainstorming: Turning Ideas into Designs

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

Start by understanding the current project context, then ask questions one 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. A to-do list, a single-function utility, a configuration change—all of them need it. "Simple" projects are exactly where untested assumptions cause the most waste. The design can be brief (a few sentences is enough for a truly simple project), but you must present it and get approval.

Checklist

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

1. Explore the project context — check files, documentation, recent commits
2. Provide a visual companion(if the topic involves visual questions) — this is a separate message; do not merge it with clarifying questions. See the "Visual Companion" section below.
3. Ask clarifying questions — one at a time, to understand purpose/constraints/success criteria
4. Propose 2-3 approaches — with trade-off analysis and your recommendation
5. Present the design — present it in sections by complexity, and get user approval after presenting each section
6. Write the design document — save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commit
7. Spec self-check — a quick inline check for placeholders, contradictions, ambiguities, scope (see below for details)
8. User reviews the written spec — ask the user to review the spec file before continuing
9. Transition to implementation — invoke the writing-plans skill to create an implementation plan

Flowchart

digraph brainstorming {
    "探索项目上下文" [shape=box];
    "有视觉相关问题?" [shape=diamond];
    "提供视觉伴侣\n（独立消息，不含其他内容）" [shape=box];
    "提出澄清问题" [shape=box];
    "提出 2-3 种方案" [shape=box];
    "分节展示设计" [shape=box];
    "用户批准设计?" [shape=diamond];
    "编写设计文档" [shape=box];
    "规格自检\n（内联修复）" [shape=box];
    "用户审查规格?" [shape=diamond];
    "调用 writing-plans 技能" [shape=doublecircle];

    "探索项目上下文" -> "有视觉相关问题?";
    "有视觉相关问题?" -> "提供视觉伴侣\n（独立消息，不含其他内容）" [label="是"];
    "有视觉相关问题?" -> "提出澄清问题" [label="否"];
    "提供视觉伴侣\n（独立消息，不含其他内容）" -> "提出澄清问题";
    "提出澄清问题" -> "提出 2-3 种方案";
    "提出 2-3 种方案" -> "分节展示设计";
    "分节展示设计" -> "用户批准设计?";
    "用户批准设计?" -> "分节展示设计" [label="否，修改"];
    "用户批准设计?" -> "编写设计文档" [label="是"];
    "编写设计文档" -> "规格自检\n（内联修复）";
    "规格自检\n（内联修复）" -> "用户审查规格?";
    "用户审查规格?" -> "编写设计文档" [label="要求修改"];
    "用户审查规格?" -> "调用 writing-plans 技能" [label="批准"];
}

The terminal state is invoking writing-plans. Do not invoke frontend-design, mcp-builder, or any other implementation skill. The only skill you should invoke after brainstorming is writing-plans.

Process Details

Understanding the idea:

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

Explore options:

• Propose 2-3 different options and their trade-offs
• Present the options in a conversational way, with your recommendation and reasoning
• Present your recommended option first and explain why

Present the design:

• Once you believe you understand what is to be built, present the design
• The length of each section should match its complexity: a few sentences for simple ones, up to 200-300 words for complex ones
• After presenting each section, ask whether it is correct
• Cover: architecture, components, data flow, error handling, testing
• Be ready to go back and clarify anything unclear at any time

Design for isolation and clarity:

• Break the system into smaller units, each with a clear responsibility, 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 looking at its internal implementation? Can you change the internal implementation without affecting callers? If not, the boundaries need adjustment.
• Smaller units with clear boundaries are also easier for you to work with—you reason better about code that fits into context at once, and the more focused a file is, the more reliable your edits are. When a file grows large, it usually means it is taking on too many responsibilities.

Working in an existing codebase:

• Explore the existing structure before proposing changes. Follow existing patterns.
• If the existing code has problems that affect the current work (for example, files that are too large, unclear boundaries, tangled responsibilities), include targeted improvements in the design—just as a good developer improves the code they touch along the way.
• Do not propose unrelated refactoring. Focus on what serves the current goal.

After the design

Documentation:

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

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

1. Placeholder scan: Are there any "TBD", "TODO", unfinished sections, or vague requirements? Fix them.
2. Internal consistency: Are there contradictions between sections? Do the architecture and feature descriptions match?
3. Scope check: Is this focused enough to be covered by a single implementation plan, or does it need further splitting?
4. Ambiguity check: Can any requirement be understood in two ways? If so, choose one and state it explicitly.

If problems are found, fix them inline directly. No need for another review—fix them and keep moving.

User review gate: After the spec self-check is complete, ask the user to review the written specification before continuing:

"The specification has been written and committed to <path>. Please review it, and let me know if you want to make any changes before we start writing the implementation plan."

Wait for the user's reply. If they ask for changes, make the changes and rerun the spec self-check. 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 — do not throw out multiple questions at once
• Prefer multiple choice — when possible, easier to answer than open-ended questions
• Strictly follow YAGNI — remove unnecessary features from all designs
• Explore alternatives — always propose 2-3 options before making a decision
• Validate incrementally — present the design, get approval, then continue
• Stay flexible — if anything is unclear, go back and clarify

Visual Companion

A browser-based companion tool for presenting prototypes, diagrams, and visual options during brainstorming. It is a tool—not a mode. Accepting the companion means it is available for questions that suit visual presentation; it does not mean every question has to go through the browser.

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

"Some of what we discuss next might be clearer if I could show it to you in the browser. I can create prototypes, diagrams, comparison charts, and other visual materials for you as we talk. This feature is still fairly new and may consume a lot of tokens. Want to try it? (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 and nothing else. Wait for the user's reply before continuing. If they decline, continue with plain-text brainstorming.

Per-question decision: Even if the user accepts, decide separately 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 it?

• Use the browser for content that is inherently visual—prototypes, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
• Use the terminal for textual content—requirements questions, concept choices, trade-off lists, A/B/C/D text options, scope decisions

Questions about UI topics are not necessarily visual questions. "What does personalization mean in this context?" is a conceptual question—use the terminal. "Which wizard layout is better?" is a visual question—use the browser.

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