brainstorming

Brainstorming: Turning Ideas into Design

Through natural collaborative dialogue, help turn ideas into complete designs and specifications.

First determine how much process this requirement needs, then proceed along the corresponding path: understand the context, refine the idea, present the design, and get approval from your human partner.

Establish Shared Understanding

The output of brainstorming is an understanding that your human partner can recognize and correct, rooted in what they want to achieve.

1. Clarify intent. Use the requirement itself and the context at hand to determine the intended outcome, who it is for, and what counts as success. When this information is missing, ask one question focused on purpose or intended use before proposing features or solutions. Knowing what type of application this is does not tell you why your partner wants it. Filling in missing requirements is not the same as asking them to authorize the task again.
2. Write your understanding back to them. Summarize the intended outcome, relevant constraints, and success criteria in a brief statement so your partner can evaluate it. Keep what they said separate from your assumptions. Ask them to correct it, and absorb their response before treating it as the design brief.
3. Carry intent into the design. Preserve this agreed understanding in the design output of the chosen path: architecture-level work is a written specification, bounded work and spikes are a design or probe plan in the conversation. Use this understanding to check every proposed feature and technical choice.

When the requirement itself already states the purpose and constraints, restate this understanding rather than asking the same questions again. Keep it brief; what matters is that it is accurate and that the other party has a chance to correct it.

• Spike: your human partner approved the problem and the probe plan.
• Bounded: your human partner approved the brief design in the conversation.
• Architecture-level: your human partner reviewed and approved the written specification, then reviewed the written implementation plan and chose the execution approach. Approval of the design in the conversation only allows you to write the specification; approval of the written specification only allows you to invoke writing-plans.

A single reply approves only the stage actually presented to the other party. Approving an idea or feature scope is not the same as approving an artifact that does not yet exist. Continue from the earliest incomplete stage; do not turn one approval into permission to skip the rest of the chosen path. While prerequisites are incomplete, read-only exploration of the project is allowed.

Three Paths

Before asking the first question, classify the requirement and state the classificationout loud— "this looks bounded, so I will give a brief design here directly rather than writing a specification document" — so your human partner can correct you:

• Spike — a feasibility question ("can we...", "is it possible...", "rough is fine"), whose output is ananswer, not code to keep. Explain the problem and how you plan to try it in 2-3 sentences, get a nod, then find out at the lowest cost that does not sacrifice correctness. No design document, no specification file. Report findings as a recommendation; anything built along the way is explicitly marked as disposable.
• Bounded — Yescode that already exists in this repositoryMake a clearly scoped change: add a switch, a small interface, fix a bug in one file. "Knowing what type of application this is" doesn't count—bounded meansthe flow you need to change is right there in the repository, readable. If there is no existing flow to change, the task is not bounded. Ask the clarification questions that really matter,in the conversationgive a brief design (a few sentences to a few short paragraphs), thenstop. Implementation begins only after your human partner says "okay" to this design—approval for a bounded task is just as hard a gate as approval for an architectural task. Don't write a spec file, don't write an implementation plan document.
• Architectural — New projects, new subsystems, and changes that restructure relationships between components or change interfaces that others depend on. Go through the full process: ask questions, compare options, section-by-section design, written spec, then hand off to the writing-plans skill.

When you're unsure between the two paths, choose the heavier one. This ratchet only turns one way: if hidden complexity is discovered while the task is underway,escalatethe path—stop, explain the situation, escalate. Under no circumstances downgrade mid-task.

Anti-pattern: "This is too simple to need approval"

Every path ends with your human partner approving the required design before implementation. A bounded change may need only two sentences in the conversation. A new to-do list item is architectural and requires a written spec and plan handoff. Scale the artifact to the chosen path; complete all reviews for that path before implementation.

Red flags

What you're thinking	The actual situation
"This is too simple to need a design"	Follow the chosen path: a bounded change gets a brief in-conversation design; an architectural change goes through a written spec and plan handoff.
"I'll just call it bounded and skip the spec document"	Reaching for a label to do less work is itself "being unsure"—choose the heavier path.
"It's bounded, and the design is obvious—I'll start work while they read it"	The gate isapproval, not the length of the design. Stop after presenting it, until you hear "okay."
"I'm very familiar with this type of application, so it's bounded"	Bounded measures therepository, not your familiarity. A new project has no existing flow to change—that's architectural.
"The spike worked, so let's keep this code"	The output of a spike is an answer. Keeping the code is anew requirement—reclassify it.
"The scope has grown, but I'm almost done, so no need to reclassify"	Hidden complexity escalates the path mid-task. Stop, explain the situation.
"They approved the spike, so the follow-up changes are approved too"	Each task has its own classification and its own approval.

Checklist

Classify first, announce the path, then create a task for each item on your path and complete them in order.

Spike:

1. Explore project context — just enough to frame the probe
2. Present the problem + probe plan — 2-3 sentences
3. Get approval — a nod is enough
4. Investigate — at the lowest cost that doesn't sacrifice correctness
5. Report findings — in the form of a recommendation; label anything you build as throwaway

Bounded:

1. Explore project context — check files, docs, recent commits
2. Ask clarifying questions — one at a time, only the ones that truly matter
3. Present a brief design in the conversation — the approach, which files will change, how to test
4. Get approval — Stopand wait for an explicit "yes"; starting work right after presenting the design means skipping the gate
5. Implement — follow the normal development workflow (TDD applies here too); don't write a plan document

Architectural:

1. Explore project context — check files, docs, recent commits
2. Offer a visual companion only when needed — Don't bring it up right away. The first time you hit "this problem is clearer drawn than said," offer it at that moment (as a separate message); once they agree, a browser tab will open for you. If no visual problem ever comes up, never mention it. 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, getting user approval after 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, ambiguity, scope (see below)
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=diamond];
    "展示问题 + 试探计划（2-3 句）" [shape=box];
    "提出澄清问题（有界）" [shape=box];
    "在对话里展示简短设计" [shape=box];
    "人类伙伴批准?" [shape=diamond];
    "动手调查；汇报建议" [shape=doublecircle];
    "走正常工作流实现（无计划文档）" [shape=doublecircle];
    "探索项目上下文" [shape=box];
    "提出澄清问题" [shape=box];
    "提出 2-3 种方案" [shape=box];
    "分节展示设计" [shape=box];
    "用户批准设计?" [shape=diamond];
    "编写设计文档" [shape=box];
    "规格自检\n（内联修复）" [shape=box];
    "用户审查规格?" [shape=diamond];
    "调用 writing-plans 技能" [shape=doublecircle];
    "发现隐藏复杂度? 升级路径" [shape=box];

    "分类：探路 / 有界 / 架构级" -> "展示问题 + 试探计划（2-3 句）" [label="探路"];
    "分类：探路 / 有界 / 架构级" -> "提出澄清问题（有界）" [label="有界"];
    "分类：探路 / 有界 / 架构级" -> "探索项目上下文" [label="架构级"];
    "展示问题 + 试探计划（2-3 句）" -> "人类伙伴批准?";
    "提出澄清问题（有界）" -> "在对话里展示简短设计";
    "在对话里展示简短设计" -> "人类伙伴批准?";
    "人类伙伴批准?" -> "动手调查；汇报建议" [label="探路：是"];
    "人类伙伴批准?" -> "走正常工作流实现（无计划文档）" [label="有界：是"];
    "发现隐藏复杂度? 升级路径" -> "分类：探路 / 有界 / 架构级";
    "探索项目上下文" -> "提出澄清问题";
    "提出澄清问题" -> "提出 2-3 种方案";
    "提出 2-3 种方案" -> "分节展示设计";
    "分节展示设计" -> "用户批准设计?";
    "用户批准设计?" -> "分节展示设计" [label="否，修改"];
    "用户批准设计?" -> "编写设计文档" [label="是"];
    "编写设计文档" -> "规格自检\n（内联修复）";
    "规格自检\n（内联修复）" -> "用户审查规格?";
    "用户审查规格?" -> "编写设计文档" [label="要求修改"];
    "用户审查规格?" -> "调用 writing-plans 技能" [label="批准"];
}

Terminal states follow the path. Architectural: after brainstorming, the only skill you invoke is writing-plans—never frontend-design, mcp-builder, or any other implementation skill. Bounded: after approval, go straight into the normal development workflow to implement, without writing a plan document. Spike: the terminal state is a recommendation you report.

Flow Details

The sections below serve theBoundedandArchitecturalpaths (Spike stops at "present the probe plan, get a nod"). FromExplore Approachesonward is the depth of the Architectural path—for Bounded work, context plus a few questions plus a brief design in the conversation is the whole process.

Understanding the idea:

• First, look at the current project state (files, docs, recent commits)
• Before asking detailed questions, assess the scope: if the requirements describe multiple independent subsystems (for example, "build a platform with chat, file storage, billing, and analytics"), point this out immediately. Don't spend time refining a project with questions when it needs to be split first.
• If the project is too large for a single spec to cover, help the user break it down into sub-projects: what are the independent parts, how do they relate to each other, 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 spec → plan → implementation cycle.
• For appropriately scoped projects, 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

Exploring approaches:

• Propose 2-3 different approaches and their trade-offs
• Present the options conversationally, with your recommendation and reasoning
• Present your recommended approach first and explain why
• Strictly follow YAGNI — remove unnecessary features from every approach and design

Presenting the design:

• Once you think you understand what is to be built, present the design
• Match the length of each section to its complexity: a few sentences for simple parts, 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, and 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 in 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 has taken 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 while working.
• Don't propose unrelated refactoring. Focus on what serves the current goal.

After the design (architecture-level path)

Documentation:

• Write the validated design (spec) to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
  • (the user's preference for the spec 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-review: After writing the spec 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 to be broken down further?
4. Ambiguity check: Are there any requirements that could be understood in two ways? If so, choose one and state it explicitly.

If you find problems, fix them inline. No need to re-review—fix them and keep going.

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

"The spec 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 re-run the spec self-check. Only continue 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.

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 problems that suit visual presentation; it does not mean every problem has to go through the browser.

Offer the companion (only when needed): Do not bring it up right away. Wait until a problem genuinely "is clearer drawn than said"—a real prototype / layout / diagram problem, not just a topic that touches on UI. The first time this happens, offer it at that moment, as a separate message:

"For this next part, it might be easier to understand if I show you—I can prototype, diagram, and compare in a browser tab during the discussion. This feature is still fairly new and may consume more tokens. Want me to open it? I'll open it for you."

This offer must be a separate message. Only this offer—no clarifying questions, content summary, or anything else. Wait for the user's reply. If they accept, use --open to start the service, and the browser will automatically open to the first screen. If they decline, continue in plain text, and do not bring it up again unless they bring it up themselves.

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

• Use the browser to present content that is itself visual—prototypes, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
• Use the terminal to present 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