brainstorm

name	brainstorm
description	Collaborative design exploration before implementation. Use when starting a new feature or project, when the approach is unclear, or when multiple design directions exist. Unlike /grill (which aligns on a given plan), /brainstorm explores and creates the plan. Enforces a HARD-GATE: no code until design is approved.

Brainstorm — Design Before Code

"No-one knows exactly what they want." — The Pragmatic Programmer

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.

Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences), but you MUST present it and get approval.

How This Differs From /grill

	/grill	/brainstorm
When	You have a task, need alignment	You have an idea, need a design
Input	User's request	Rough idea or problem statement
Output	Verified implementation plan	Approved design document
Focus	"Are we building the right thing?"	"What should we build?"
Depth	Assumptions + success criteria	Full design exploration

Use /brainstorm first, then /grill to refine, then /to-prd to formalize.

Workflow

Copy this checklist and track your progress:

Brainstorm Progress:
- [ ] Step 1: Explore project context
- [ ] Step 2: Ask clarifying questions (one at a time)
- [ ] Step 3: Propose 2-3 approaches with trade-offs
- [ ] Step 4: Present design in sections
- [ ] Step 5: Write design doc
- [ ] Step 6: Spec self-review
- [ ] Step 7: User reviews and approves

Step 1: Explore Project Context

Check files, docs, recent commits. Understand what exists before proposing what's new.

Step 2: Ask Clarifying Questions

• One question at a time — don't overwhelm
• Prefer multiple choice when possible
• Focus on: purpose, constraints, success criteria
• If the request describes multiple independent subsystems, flag this immediately and help decompose

Step 3: Propose 2-3 Approaches

For each approach:

• What it is
• Pros and cons
• Your recommendation and why

Lead with your recommended option.

Step 4: Present Design in Sections

• Scale each section to its complexity (a few sentences if straightforward)
• Ask after each section whether it looks right
• Cover: architecture, components, data flow, error handling, testing
• Be ready to go back and clarify

Step 5: Write Design Doc

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

# Design: [Feature Name]

## Problem
[What problem? For whom?]

## Approach
[Chosen approach and why]

## Architecture
[Components, data flow, interfaces]

## Requirements
### Must Have
- [Requirement]

### Nice to Have
- [Requirement]

## Non-Goals
[What we're NOT building]

## Success Criteria
- [ ] [Measurable criterion]

## Open Questions
- [Question]

Step 6: Spec Self-Review

After writing the spec, check for:

1. Placeholders — Any "TBD", "TODO", incomplete sections? Fix them.
2. Internal consistency — Do sections contradict each other?
3. Scope check — Is this focused enough, or does it need decomposition?
4. Ambiguity check — Could any requirement be interpreted two ways?

Fix issues inline. No need to re-review — just fix and move on.

Step 7: User Reviews and Approves

Ask the user to review the written spec before proceeding. Wait for approval.

Key Principles

• One question at a time — Don't overwhelm
• YAGNI ruthlessly — Remove unnecessary features from all designs
• Explore alternatives — Always propose 2-3 approaches
• Incremental validation — Present design, get approval before moving on
• Design for isolation — Small units with clear purpose and well-defined interfaces

Anti-Patterns

• Skipping the HARD-GATE — "This is simple" is not an excuse
• Rubber-stamping — Repeating the idea without thinking
• Analysis paralysis — 20 minutes brainstorming on a 5-minute task
• Scope creep — Adding features the user didn't ask for

Integration

• Use /brainstorm → /grill → /to-prd → /to-issues → /tdd for full workflow
• Use /zoom-out during brainstorming for system context
• Use /architect if brainstorming reveals architectural issues
• Update CONTEXT.md with new domain terms discovered during brainstorming