Brainstorming: From Idea to Design

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

Checklist

1. Explore Project Context — Check files, documents, recent commits
2. Offer Visual Companion Timely — Do not offer it at the start. When a problem is clearer to "see" than to "say", propose it at that moment (in a separate message); open a browser tab for them after the user agrees. If visualization is not needed throughout the process, don't mention it. See the "Visual Companion" section below for details.
3. Ask Clarifying Questions — Ask one at a time, understand the purpose/constraints/success criteria
4. Propose 2-3 Solutions — Include trade-off analysis and your recommendation
5. Present Design — Display by complexity sections, obtain user approval after each section
6. Write Design Document — Save to

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

   and commit
7. Self-Review Specification — Quickly check for placeholders, contradictions, ambiguities, scope (see below)
8. User Reviews Specification — Ask the user to review the specification document before proceeding
9. Transition to Implementation — Create an implementation plan and start working

Flowchart

Explore Project Context → Ask Clarifying Questions → Propose 2-3 Solutions → Present Design by Sections
    ↓
User Approves Design? —[No, Modify]→ Return to Present Design
    ↓ Yes
Write Design Document → Self-Review Specification (Fix on the Spot) → User Reviews Specification?
    ↓                                      ↓ Need Modification → Return to Write Design Document
    ↓                                      ↓ Approved
    └──────────────────────────────────── Start Implementation

Process Details

• First understand the current project status (files, documents, recent commits)
• Assess the scope before diving into questions: If the requirements describe multiple independent subsystems (e.g., "Build a platform with chat, file storage, billing, and analytics"), point this out immediately. Don't spend time refining a project that needs to be split first
• If the project is too large for a single specification, help the user break it into sub-projects: 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 sub-project. Each sub-project has its own specification → plan → implementation cycle
• For projects with appropriate scope, ask questions one by one to refine the idea
• Use multiple-choice questions as much as possible; open-ended questions are also acceptable
• Ask only one question per message — if a topic needs more discussion, split it into multiple questions
• Focus on: purpose, constraints, success criteria

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

• Once you think you understand what needs to be built, present the design
• The level of detail for each section matches its complexity: a few sentences for simple parts, up to 200-300 words for complex ones
• Ask the user if each section is correct after presenting it
• Cover: architecture, components, data flow, error handling, testing
• Be prepared to go back and clarify if something is unclear

• 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 someone understand the function of a unit without looking at its internal implementation? Can the internal implementation be modified without breaking the users? If not, the boundaries need to be redefined
• Smaller, clearly bounded units are also easier to handle — reasoning is more accurate and editing is more reliable for code that can be fully contained in context. When files become large, it usually means they are doing too much

• Understand the existing structure before proposing changes. Follow existing patterns
• If issues in the existing code affect the current work (e.g., overly large files, unclear boundaries, tangled responsibilities), include targeted improvements in the design — just like a good developer would improve the code they touch while working
• Do not propose unrelated refactoring. Focus on the current goal

After Design

• Write the validated design (specification) into

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

  • (User preferences for specification storage location take precedence over this default path)
• Write clearly and concisely — short sentences, active voice, specific details are better than vague generalizations
• Commit the design document to git

1. Placeholder Scan: Are there "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. Internal Consistency: Are there contradictions between sections? Does the architecture match the functional description?
3. Scope Check: Is this focused enough to support an implementation plan? Or does it need to be split?
4. Ambiguity Check: Is there any requirement that could be interpreted in two ways? If so, choose one and write it clearly.

spec-document-reviewer-prompt.md

"The specification has been written and committed to

<path>

. Please review it and let me know if you have any modification suggestions. If everything is okay, we will start implementation."

• After approval, create a detailed step-by-step implementation plan
• Split 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
• Prioritize multiple-choice questions — Easier to answer than open-ended questions
• Strictly follow YAGNI — Remove unnecessary features from the design
• Explore alternatives — Always propose 2-3 solutions before deciding
• Progressive validation — Present the design and obtain approval before proceeding
• Stay flexible — Go back to clarify if something is wrong

Visual Companion

"The next part might be clearer to see than to explain — I can show you mockups, diagrams, and comparisons in a browser tab. This feature is relatively new and will consume more tokens. Would you like me to enable it?"

--open

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

visual-companion.md