brainstorming

Brainstorming: From Idea to Design

Through natural collaborative dialogue, help users turn ideas into complete designs and specification documents.

First understand the current project context, then ask questions one by one to refine the idea. Once you understand what is to be built, present the design and get user approval.

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

Once this skill is triggered, even if the project seems very simple (a todo list, a single-function tool), still go through the design process. "Simple" projects are precisely the ones most likely to waste effort because of untested assumptions. The design can be very short (just a few sentences for a truly simple project), but it must be presented and approved.

Checklist

A task must be created for each of the following items, and completed in order:

Explore project context — check files, documentation, recent commits
Offer a visual companion at the right time — do not offer it at the beginning. When a question is clearer to "see" than to "say," raise it at that moment (as a separate message); after the user agrees, open a browser tab for them. If the whole process does not need visualization, do not mention it. See the "Visual Companion" section below for details.
Ask clarifying questions — one at a time, to understand purpose/constraints/success criteria
Propose 2-3 options — with trade-off analysis and your recommendation
Present the design — show it in sections by complexity, and get user approval after each section
Write the design document — save to docs/specs/YYYY-MM-DD-<主题>-design.md and commit
Spec self-review — quickly check for placeholders, contradictions, ambiguity, scope (see below)
User reviews the spec — ask the user to review the spec file before continuing
Transition to implementation — create an implementation plan and start work

Flowchart

探索项目上下文 → 提出澄清问题 → 提出 2-3 个方案 → 分节呈现设计
    ↓
用户认可设计？ —[否，修改]→ 返回呈现设计
    ↓ 是
编写设计文档 → 规格自审（就地修复） → 用户审阅规格？
    ↓                                      ↓ 需要修改 → 返回编写设计文档
    ↓                                      ↓ 通过
    └──────────────────────────────────── 开始实现

The terminal state is to start implementation. After the user approves the spec, create a step-by-step implementation plan and start coding.

Process Details

Understanding the idea:

First understand the current project state (files, documentation, recent commits)
Assess scope before asking in-depth questions: 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 refining a project that needs to be split first
If the project is too large for one spec, help the user break it down into subprojects: what are the independent parts, how do they relate, and in what order should they be built? Then follow the normal design process for the first subproject. Each subproject has its own spec → plan → implementation cycle
For projects with appropriate scope, ask questions one by one to refine the idea
Use multiple-choice questions when possible; open-ended is also fine
Ask only one question per message — if a topic needs more exploration, split it into multiple questions
Focus on: purpose, constraints, success criteria

Exploring options:

Propose 2-3 different options and their trade-offs
Present the options conversationally, with your recommendation and reasoning
Say which option you recommend first and explain why

Presenting the design:

Once you believe you understand what is to be built, present the design
The level of detail in each section matches its complexity: a few sentences for simple ones, and for complex ones, write until it is clear.
After each section, ask the user whether it is correct.
Cover: architecture, components, data flow, error handling, testing.
Be prepared to go back and clarify when something is unclear.

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 others understand what a unit does without looking at its internal implementation? Can the internal implementation be changed without breaking users? If not, the boundaries need to be redrawn.
Smaller units with clear boundaries are also easier to work with—reasoning is more accurate and editing is more reliable for code that fits fully in context. When a file becomes very large, it usually means it is doing too much.

Working in an existing codebase:

Understand the existing structure before proposing changes. Follow existing patterns.
If problems in the existing code affect the current work (for example, files that are too large, unclear boundaries, entangled responsibilities), incorporate targeted improvements into the design—just as a good developer improves the code they touch while working.
Do not propose unrelated refactoring. Focus on the current goal.

After design

Documentation:

Write the validated design (spec) to docs/specs/YYYY-MM-DD-<主题>-design.md
- (the user's preference for where the spec is stored takes precedence over this default path)
Write clearly and concisely—short sentences, active voice, and specific details are better than vague generalizations.
Commit the design document to git.

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

Placeholder scan: Are there "TBD"s, "TODO"s, unfinished sections, or vague requirements? Fix them.
Internal consistency: Are there contradictions between sections? Does the architecture match the feature description?
Scope check: Is this focused enough to support an implementation plan? Or does it need to be split?
Ambiguity check: Is there any requirement that could be understood in two ways? If so, choose one and write it explicitly.

Fix problems in place. No need to re-review—continue after fixing. For complex specs, you can refer to spec-document-reviewer-prompt.md(in this skill directory) to dispatch a subagent for an independent review.

User review gate: After the spec self-review passes, ask the user to review:

"The spec has been written and committed to <路径>. Please review it, and let me know if you have any changes. If it looks good, we'll start implementation."

Wait for the user's reply. If changes are requested, revise and then self-review again. Continue only after the user approves.

Implementation:

After approval, create a detailed step-by-step implementation plan.
Break the work into small, verifiable increments.
Start implementation according to the plan.

Core principles

Ask only one question at a time — do not bombard the user with multiple questions
Prefer multiple-choice questions — easier to answer than open-ended questions
Strict YAGNI — Remove unnecessary features from the design
Explore alternatives — Always propose 2-3 options before deciding
Incremental validation — Present the design, get approval, then continue
Stay flexible — Go back and clarify when you find something is wrong

Visual companion

A browser-based companion tool for presenting 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 need visual handling; it does not mean every problem goes through the browser.

Offer just-in-time: Do not offer it at the start. Wait until a problem is genuinely clearer by "seeing" than by "saying" — a real mockup/layout/diagram problem, not just atopicthat involves UI. The first time this happens, send a separate message proposing it:

"This next part might be clearer by seeing than by saying — I can show you mockups, diagrams, and comparisons in a browser tab. This feature is relatively new and will consume more tokens. Shall I open it?"

This proposal must be a separate message. Do not attach any clarifying questions, summaries, or other content. Wait for the user's reply. If accepted, use --open to start the server so the browser opens automatically. If declined, continue in plain-text mode and do not offer it again (unless the user brings it up).

Decide per problem: Even if the user has accepted the companion, decide for each problem whether to use the browser or the terminal. The criterion:Would the user understand it better by seeing it than by reading it?

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

Questions about UI topics are not automatically visual questions. "What does 'personalization' mean in this context?" is a conceptual question — use the terminal. "Which of these two wizard layouts is better?" is a visual question — use the browser.

If the user agrees to use the companion, read the detailed guide before continuing: visual-companion.md(in this skill directory)