Brainstorming: Turning Ideas into Designs

Anti-pattern: "This is too simple, no design needed"

Checklist

1. Explore Project Context — Check files, documents, recent commits
2. Provide Visual Companion (if the topic involves visual issues) — This is a separate message, do not combine with clarification questions. See the "Visual Companion" section below.
3. Ask Clarification Questions — One at a time, understand the purpose/constraints/success criteria
4. Propose 2-3 Solutions — With trade-off analysis and your recommendation
5. Present Design — Present in sections by complexity, obtain user approval after each section
6. Write Design Document — Save to

   docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md

   and commit
7. Specification Self-Check — Quick inline check for placeholders, contradictions, ambiguity, scope (details below)
8. User Review of Written Specification — Ask the user to review the specification document before proceeding
9. Transition to Implementation — Call 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="批准"];
}

Process Details

• First check the current project status (files, documents, recent commits)
• Before asking detailed questions, assess the scope: if the requirements describe multiple independent subsystems (e.g., "Build a platform with chat, file storage, billing, and analytics"), point this out immediately. Do not spend time refining a project that needs to be split first with questions.
• If the project is too large to be covered by a single specification, help the user break it down into sub-projects: what are the independent parts, what is the relationship between them, and in what order should they be built? Then brainstorm the first sub-project through the normal design process. Each sub-project has its own specification → plan → implementation cycle.
• For projects with appropriate scope, ask one question at a time to refine the idea
• Try to use multiple-choice questions; open-ended questions are also acceptable
• Only ask one question per message—if a topic requires more exploration, split it into multiple questions
• Focus on understanding: purpose, constraints, success criteria

• Propose 2-3 different solutions and their trade-offs
• Present options in a conversational manner, with your recommendation and reasons
• Present your recommended solution first and explain why

• Once you think you understand what needs to be built, present the design
• The length of each section matches its complexity: a few sentences for simple parts, up to 200-300 words for complex parts
• After presenting each section, ask if it is correct
• Cover: architecture, components, data flow, error handling, testing
• Be ready to go back and clarify ambiguous points at any time

• Split the system into smaller units, each with a clear responsibility, communicating through well-defined interfaces, which can be understood and tested independently
• For each unit, you should be able to answer: what does it do, how to use it, what does it depend on?
• Can others understand the function of a unit without looking at its internal implementation? Can you modify the internal implementation without affecting the caller? If not, the boundaries need to be adjusted.
• Smaller, clearly bounded units also make your work easier—you reason better about code that fits into context at once, and your edits are more reliable when files are focused. When a file grows large, it usually means it is taking on too many responsibilities.

• Explore the existing structure before proposing changes. Follow existing patterns.
• If there are issues in the existing code that affect the current work (e.g., overly large files, unclear boundaries, tangled responsibilities), include targeted improvements in the design—just like a good developer improves the code they work on.
• Do not propose unrelated refactoring. Focus on things that serve the current goal.

After Design

• Write the validated design (specification) to

  docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md

  • (User preferences for specification location take precedence over this default)
• If available, use the elements-of-style:writing-clearly-and-concisely skill
• Commit the design document to git

1. Placeholder Scan: Are there "TBD", "TODO", unfinished sections, or vague requirements? Fix them.
2. Internal Consistency: Are there contradictions between sections? Do the architecture and functional descriptions match?
3. Scope Check: Is this focused enough to be covered by one implementation plan, or does it need further splitting?
4. Ambiguity Check: Are there requirements that can be interpreted in two ways? If so, choose one and write it clearly.

"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."

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

Core Principles

• One Question at a Time — Do not throw multiple questions at once
• Prioritize Multiple-Choice Questions — Easier to answer than open-ended questions when possible
• Strictly Follow YAGNI — Remove unnecessary features from all designs
• Explore Alternatives — Always propose 2-3 solutions before making a decision
• Incremental Validation — Present the design and obtain approval before proceeding
• Stay Flexible — Go back and clarify ambiguous points when they arise

Visual Companion

"Some of the content we'll discuss next might be more intuitive if shown to you in a browser. I can create prototypes, diagrams, comparison charts, and other visual materials for you during the discussion. This feature is relatively new and may consume more tokens. Would you like to try it? (Requires opening a local URL)"

• Use Browser to display content that is inherently visual—prototypes, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
• Use Terminal to display text-based content—requirement questions, concept choices, trade-off lists, A/B/C/D text options, scope decisions

skills/brainstorming/visual-companion.md