georgekhananaev/brainstorm

Brainstorm

Transform ideas into fully-formed designs and specs through natural collaborative dialogue.

When to Use

• User has an idea that needs refinement ("I want to add...")
• Feature requires design exploration before implementation
• Multiple valid approaches exist and trade-offs need evaluation
• Requirements are unclear or partially defined
• User explicitly asks to brainstorm, design, or spec out a feature

The Process

Phase 1: Context Gathering

Before asking questions, understand the current state:

1. Check project structure (Glob key directories)
2. Review recent commits (git log --oneline -10)
3. Read relevant existing code/docs
4. Identify patterns and conventions already in use

Phase 2: Idea Refinement

Core Principle: One question at a time.

Ask questions to understand the idea. Prefer multiple-choice when possible:

Use AskUserQuestion with:
- 2-4 options per question
- Clear, mutually exclusive choices
- Your recommended option first (with reasoning)

Question Categories:

| Category | Example Questions | |----------|-------------------| | Purpose | What problem does this solve? Who benefits? | | Constraints | Must integrate with X? Budget/time limits? | | Success | How do we know it worked? Key metrics? | | Scope | What's explicitly NOT included? | | Prior Art | Seen similar elsewhere? What worked/didn't? |

Exit Criteria: Stop asking when purpose, constraints, and success criteria are clear.

Phase 3: Approach Exploration

Present 2-3 approaches with trade-offs:

## Approach A: [Name] (Recommended)
- **Pros**: ...
- **Cons**: ...
- **Best when**: ...

## Approach B: [Name]
- **Pros**: ...
- **Cons**: ...
- **Best when**: ...

Lead with recommendation and explain why. Ask user to confirm or discuss.

Phase 4: Incremental Design Presentation

Once approach is selected, present the design in sections:

CRITICAL: Each section must be 200-300 words max.

After each section, ask:

"Does this section look right so far? Any adjustments needed?"

Section Order:

1. Overview - Goal, scope, success metrics
2. Architecture - Components, data flow, boundaries
3. Data Model - Schema, relationships (if applicable)
4. Error Handling - Failure modes, recovery strategies
5. Testing Strategy - What to test, how to test

Only proceed to next section after user confirms current section.

Be flexible: If something doesn't make sense, go back and clarify. The process is not rigid.

Phase 5: Documentation

After all sections validated:

1. Compile into single design document
2. Use elements-of-style skill for clarity
3. Write to docs/plans/YYYY-MM-DD-<topic>-design.md
4. Commit the design document to git

Phase 6: Implementation Setup (Optional)

After documentation is complete, ask:

"Ready to set up for implementation?"

If yes:

1. Use using-git-worktrees to create isolated workspace
2. Use /plan-feature command to create detailed implementation plan with TDD tasks

Question Patterns

Good Questions (Multiple Choice)

AskUserQuestion:
  question: "How should we handle failed API calls?"
  options:
    - label: "Retry with backoff (Recommended)"
      description: "Automatic retry 3x with exponential backoff. Best for transient failures."
    - label: "Fail immediately"
      description: "Return error to user right away. Simpler but less resilient."
    - label: "Queue for later"
      description: "Store and retry in background. Good for non-critical operations."

Good Questions (Open-ended)

Use when options aren't clear-cut:

• "What existing functionality should this integrate with?"
• "Are there any similar features in other products you'd like to emulate?"
• "What's the worst-case failure scenario we need to handle?"

YAGNI Ruthlessly

During design, actively remove unnecessary features:

| Red Flag | Question to Ask | |----------|-----------------| | "It might be useful to..." | "Do we need this for MVP?" | | "We could also add..." | "Is this solving the stated problem?" | | "Just in case..." | "What's the likelihood this is needed?" | | "This would be nice..." | "Is this a requirement or a want?" |

Default answer: Remove it. Can always add later.

Design Document Template

# Feature: [Name]
Date: YYYY-MM-DD

## 1. Overview
**Goal**: [One sentence]
**Success Metrics**: [How we measure success]
**In Scope**: [What we're building]
**Out of Scope**: [What we're NOT building]

## 2. Architecture
[Diagram or description of components]

### Data Flow
[Step-by-step flow]

## 3. Data Model (if applicable)
[Schema changes, relationships]

## 4. Error Handling
| Scenario | Response |
|----------|----------|
| ... | ... |

## 5. Testing Strategy
| Type | Coverage | Focus |
|------|----------|-------|
| Unit | ... | ... |
| Integration | ... | ... |
| E2E | ... | ... |

## 6. Open Questions
[Any unresolved decisions]

Anti-Patterns

| Don't | Do Instead | |-------|------------| | Ask 5 questions at once | One question per message | | Present design all at once | 200-300 word sections, validate each | | Skip context gathering | Always check project state first | | Present only one approach | Always show 2-3 with trade-offs | | Assume requirements | Ask until crystal clear | | Over-engineer MVP | YAGNI - remove the unnecessary | | Write design without validation | Get user confirmation at each step |

Execution Flow

CONTEXT → REFINE → EXPLORE → PRESENT → DOCUMENT → IMPLEMENT
   │         │         │         │          │          │
 Git/Files  1 Q at   2-3 opts  200-300   docs/plans/  git-worktrees
            a time   w/recs    sections  + commit     + /plan-feature

---

Integration

Pairs with:

• gemini-cli - Get alternative perspectives during approach exploration (Phase 3)
• elements-of-style - Apply when writing design documents (Phase 5)
• using-git-worktrees - Create isolated workspace for implementation (Phase 6)
• /plan-feature command - Create detailed TDD implementation plans (Phase 6)