brainstorming

Overview

Brainstorming turns vague ideas into validated designs through structured Socratic dialogue. It prevents the most expensive mistake in software: building the wrong thing. Every project — no matter how "simple" — goes through this process.

When to Use

Before ANY creative work: new features, components, behaviors
When a user describes something they want built
When requirements are ambiguous or underspecified
NOT mid-implementation (if requirements change mid-build, pause and re-brainstorm)
NOT for simple bug fixes with clear reproduction steps

<HARD-GATE> Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. </HARD-GATE>

Process

Phase 1: Understand Context

Explore the project. Check files, docs, recent commits, existing patterns. Understand what exists before proposing what's new.
Assess scope. If the request spans multiple independent subsystems, flag this immediately. Large projects need decomposition before design — don't refine details of something that should be split.
Offer visual companion (if visual questions ahead). This is its own message — never combined with other content:

"Some of what we're working on might be easier to explain with visuals. I can show mockups, diagrams, and comparisons in a browser. Want to try it?"

Phase 2: Clarify Intent

Ask questions ONE at a time. Not a list of 5 questions. One question per message.
Prefer multiple-choice when possible. Easier to answer than open-ended.
Focus on: Purpose (why), constraints (what limits), success criteria (how you'll know it works).
Stop when you understand: What should happen, what should NOT happen, who uses it, and how success is measured.

Phase 3: Explore Approaches

Propose 2-3 approaches with tradeoffs. Never present a single option.
Lead with your recommendation and explain why.
Include for each approach: Architecture, complexity, timeline, risks, limitations.

Phase 4: Present Design

Present the design section by section. Scale each section to its complexity — a few sentences if simple, up to 200-300 words if nuanced.
Ask after each section: "Does this look right so far?"
Cover: Architecture, components, data flow, error handling, testing strategy, security considerations.
Design for isolation: Break the system into units that each have one clear purpose, communicate through well-defined interfaces, and can be tested independently.

Phase 5: Document & Gate

Write the design doc. Save to docs/specs/YYYY-MM-DD-<topic>-design.md.
Self-review the spec:
- Placeholder scan: Any TBD, TODO, or vague requirements? Fix them.
- Internal consistency: Do sections contradict each other?
- Scope check: Is this focused enough for a single implementation?
- Ambiguity check: Could any requirement be read two ways?
User review gate: Ask the user to review the written spec.
Only after approval: Transition to codehands:planning-and-task-breakdown.

Working in Existing Codebases

Explore the current structure BEFORE proposing changes
Follow existing patterns. Don't introduce new paradigms without justification.
If existing code has problems related to your work (overgrown file, tangled boundaries), include targeted improvements — don't propose unrelated refactoring.

Key Principles

One question at a time — don't overwhelm
Multiple choice preferred — lower cognitive load
YAGNI ruthlessly — remove features you don't need yet
Always 2-3 options — never present a single approach
Incremental validation — get approval at each stage
Design can be short — a 3-sentence design for a trivial task is fine. Skipping design entirely is not.

Common Rationalizations

Rationalization	Reality
"This is too simple to need a design"	Simple projects are where unexamined assumptions cause the most wasted work. The design can be 3 sentences, but you MUST present it.
"The user clearly knows what they want"	Even clear requests contain ambiguity. "Build a login page" has 20+ design decisions hidden in it. Surface them.
"I'll just start and iterate"	Starting without a design means iterating from a random point. Design first so iteration moves toward the goal, not sideways.
"Asking too many questions will annoy the user"	Asking the right questions saves the user hours of rework. One well-placed question prevents days of wasted effort.
"I can see the whole design in my head"	You can't. You're predicting what the user wants based on patterns. Your mental model has gaps — surface them through questions.

Red Flags

Jumping to code before presenting a design
Asking 5+ questions in a single message
Presenting only one approach ("here's what I'll build")
Skipping the spec self-review
Not exploring existing code before designing changes
Proposing a design without asking about constraints or success criteria

Verification

Project context explored (existing files, patterns, recent changes)
Clarifying questions asked one at a time
2-3 approaches proposed with tradeoffs and recommendation
Design presented section by section with user approval at each stage
Design doc written and saved to docs/specs/
Spec self-review completed (no TBDs, no contradictions, scope focused)
User has reviewed and approved the spec
NO code was written before design approval