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:

• Overview - Goal, scope, success metrics

• Architecture - Components, data flow, boundaries

• Data Model - Schema, relationships (if applicable)

• Error Handling - Failure modes, recovery strategies

• 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:

• Compile into single design document

• Use elements-of-style skill for clarity

• Write to docs/plans/YYYY-MM-DD-<topic>-design.md

• Commit the design document to git

Phase 6: Implementation Setup (Optional)

After documentation is complete, ask:

"Ready to set up for implementation?"

If yes:

• Use using-git-worktrees to create isolated workspace

• 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

5. Testing Strategy

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)