brainstorming

What this skill does

# Brainstorming Ideas Into Designs

## Overview

Brainstorming transforms vague ideas into validated designs through structured collaborative dialogue. It bridges the gap between "I want X" and a concrete design that can be handed to the planning skill. This enhanced version integrates with the self-learning skill to build on known project context and avoid re-asking previously answered questions.

**Announce at start:** "I'm using the brainstorming skill to explore this idea and create a design before implementation."

## Trigger Conditions

- User describes a new feature idea or goal
- User asks "how should we build X?"
- Creative work requires design exploration before planning
- `/brainstorm` command invoked
- Transition from a vague requirement to structured design is needed

---

## Phase 1: Context Loading

**Goal:** Load everything known about the project before asking the user anything.

1. Check memory files (`project-context.md`, `learned-patterns.md`, `decisions-log.md`) for known patterns, stack, and conventions
2. Read relevant existing code, docs, and recent commits
3. Review existing designs in `docs/plans/` for related prior work
4. Identify constraints from the existing architecture
5. Note what you already know — do NOT re-ask the user for information you can discover

### Context Sources Priority

| Source | What to Extract | Priority |
|--------|----------------|----------|
| Memory files | Stack, conventions, past decisions | Highest |
| CLAUDE.md | Project structure, hard gates | High |
| Existing code | Current patterns, architecture | High |
| Recent commits | Direction of development | Medium |
| docs/plans/ | Prior designs and decisions | Medium |

**STOP — Do NOT proceed to Phase 2 until:**
- [ ] Memory files have been checked
- [ ] Relevant codebase areas have been explored
- [ ] You can summarize what you already know about this domain

---

## Phase 2: Idea Exploration

**Goal:** Understand the user's intent through focused, one-at-a-time questions.

1. Ask ONE question per message — never multiple questions
2. Prefer multiple choice questions when possible
3. Focus on understanding purpose, constraints, and success criteria
4. Build on context loaded in Phase 1 — skip questions you can already answer
5. Convert vague answers into specific, testable criteria

### Question Flow Decision Table

| What You Need to Know | Question Type | Example |
|-----------------------|--------------|---------|
| Core purpose | Open-ended | "What problem does this solve for the user?" |
| Scope boundaries | Multiple choice | "Should this handle: (A) only logged-in users, (B) all users, (C) depends on role?" |
| Technical constraints | Yes/No + follow-up | "Does this need to work offline?" |
| Priority trade-offs | Forced ranking | "Rank these: speed, correctness, simplicity" |
| Success criteria | Measurable target | "What does 'working' look like? Can you describe the happy path?" |
| Non-goals | Explicit exclusion | "What should we explicitly NOT build in this iteration?" |

### Question Rules

| Rule | Rationale |
|------|-----------|
| One question per message | Prevents cognitive overload |
| Multiple choice preferred | Faster to answer, reduces ambiguity |
| Research before asking | Respect user's time |
| Build on memory | Do not re-ask known things |
| Testable outcomes | Vague success criteria lead to vague designs |

**STOP — Do NOT proceed to Phase 3 until:**
- [ ] You understand the core purpose and who it serves
- [ ] You know the constraints (technical, timeline, scope)
- [ ] You have identified success criteria and non-goals
- [ ] No critical ambiguities remain about intent

---

## Phase 3: Approach Exploration

**Goal:** Propose 2-3 distinct approaches with trade-offs and a clear recommendation.

For each approach, present:

| Section | Content |
|---------|---------|
| Name | Short descriptive label |
| Architecture summary | 2-3 sentences |
| Key trade-offs | Pros and cons |
| Complexity | Low / Medium / High |
| Risk | What could go wrong |
| Your assessment | Why you do or do not recommend it |

### Approach Comparison Template

```
## Approach A: [Name] (Recommended)
**Summary:** [2-3 sentences]
**Pros:** [list]
**Cons:** [list]
**Complexity:** [Low/Medium/High]
**Risk:** [What could go wrong]
**Why recommended:** [1-2 sentences]

## Approach B: [Name]
...

## Approach C: [Name] (if needed)
...
```

**Lead with your recommended approach** and explain why it is the best fit given the constraints discussed in Phase 2.

**STOP — Do NOT proceed to Phase 4 until:**
- [ ] You have proposed at least 2 approaches
- [ ] Each approach has explicit trade-offs
- [ ] You have made a clear recommendation
- [ ] User has indicated which approach to pursue

---

## Phase 4: Design Presentation

**Goal:** Present the detailed design in sections, getting approval incrementally.

1. Present the design in logical sections scaled to complexity
2. Ask after each section whether it looks right so far
3. Be ready to go back and revise any section based on feedback
4. Cover all relevant design dimensions

### Design Sections by Complexity

| Complexity | Required Sections | Optional Sections |
|-----------|-------------------|-------------------|
| Simple (1-3 tasks) | Architecture, Components | — |
| Medium (4-10 tasks) | Architecture, Components, Data Flow, Error Handling | Testing Strategy |
| Complex (10+ tasks) | Architecture, Components, Data Flow, Error Handling, Testing Strategy, Performance, Security | Migration Plan |

### Section Presentation Order

1. **Architecture** — High-level structure and key decisions
2. **Components** — What pieces exist and how they relate
3. **Data Flow** — How data moves through the system
4. **Error Handling** — What can go wrong and how to handle it
5. **Testing Strategy** — How to verify correctness
6. **Performance** — Only if relevant constraints exist
7. **Security** — Only if handling sensitive data or auth

Present one section at a time. Wait for user confirmation before proceeding.

**STOP — Do NOT proceed to Phase 5 until:**
- [ ] All relevant design sections have been presented
- [ ] User has approved each section (or revisions were made)
- [ ] The complete design is coherent and addresses all requirements

---

## Phase 5: Documentation and Transition

**Goal:** Persist the design and hand off to the planning skill.

1. Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
2. Commit the design document
3. Update self-learning memory:
   - `memory/decisions-log.md` — any architectural decisions made
   - `memory/learned-patterns.md` — any new conventions discussed
4. Invoke the `planning` skill to create a detailed implementation plan

### Design Document Template

```markdown
# [Topic] Design Document

**Date:** YYYY-MM-DD
**Status:** Approved
**Approach:** [Which approach was chosen]

## Problem Statement
[What problem this solves and for whom]

## Design

### Architecture
[High-level structure]

### Components
[Key pieces and their relationships]

### Data Flow
[How data moves through the system]

### Error Handling
[What can go wrong and how it is handled]

## Decisions Made
- [Decision 1]: [Rationale]
- [Decision 2]: [Rationale]

## Non-Goals
- [What was explicitly excluded and why]

## Next Steps
Invoke planning skill to create implementation plan.
```

**STOP — Do NOT proceed until:**
- [ ] Design document is saved to `docs/plans/`
- [ ] Memory files are updated with new decisions/patterns
- [ ] User has confirmed the design is complete

---

## Anti-Patterns / Common Mistakes

| Anti-Pattern | Why It Fails | Correct Approach |
|-------------|-------------|-----------------|
| "This is too simple to brainstorm" | Every project needs a design, even simple ones | Design can be brief, but must exist |
| "The user already knows what they want" | Users know WHAT, not HOW | Explore the HOW through approaches |
| "I can just start coding" | Code without design is technic