---
name: brainstorm
user-invocable: true
description: Explores requirements and approaches through collaborative dialogue before planning implementation.
when_to_use: Use when user says "brainstorm", "explore idea", "what should we build", "think through this", or "let's discuss approaches".
argument-hint: feature or idea to explore
compatibility: Designed for Claude Code (or similar products with agent support)
---

# Brainstorm a feature or improvement

Clarify **WHAT** to build before diving into **HOW** to build it. Explore user intent, approaches, and design decisions through collaborative dialogue.

## Feature description

<feature description>$ARGUMENTS</feature description>

**If the feature description above is empty, ask the user**: "What feature would you like to brainstorm? Describe the idea, problem or feature you are thinking about."

DO NOT proceed until you have a description from the user.

## Execution flow

### 0. Assess scope and workspace

Determine whether this is a **new project** or a **feature for the current project**.

| Signal | Conclusion |
|--------|------------|
| User says "new app", "new project", "build from scratch"; no relevant code in working directory | New project |
| User references existing code/screens; idea extends current functionality | Feature for current project → skip to Step 0.1 |

**If new project**, use **AskUserQuestion**: "This sounds like a new project. Where would you like to work?"

1. **Create project first (Recommended)** — output instructions to run `/create`, open the new folder, then `/brainstorm <description>` in that workspace. Then stop.
2. **Continue here** — proceed to Step 0.1

### 0.1. Assess clarity of requirements

Assess whether brainstorming is needed.

| Requirements are clear | Brainstorming is needed |
|------------------------|------------------------|
| Specific acceptance criteria provided | Vague terms ("make it better", "add something like") |
| Exact behavior described, scope constrained | Multiple reasonable interpretations, trade-offs undiscussed |

**If clear:** Use **AskUserQuestion** to suggest proceeding directly to planning.

### 1. Understand the idea

#### 1.1. Lightweight project research

Run a quick project review to understand existing patterns:

- Task @codebase-review-agent("Understand existing patterns related to: <feature_description>")

Focus on: similar features, established patterns, CLAUDE.md guidance.

#### 1.2. Collaborative conversation

Use the **AskUserQuestion tool** to ask questions one at a time. The tool automatically provides an "Other" option for free-text input — never add your own catch-all option (e.g., "Something else", "None of the above").

**Question Techniques:** Prefer multiple choice over open-ended. Start broad (purpose, users) then narrow (constraints, edge cases). Validate assumptions explicitly. Ask about success criteria early.

**Key Topics to Explore:**

| Topic | Example Questions |
|-------|-------------------|
| Purpose | What problem does this solve? What's the motivation? |
| Users | Who uses this? What's their context? |
| Constraints | Any technical limitations? Timeline? Dependencies? |
| Success | How will you measure success? What's the happy path? |
| Edge Cases | What shouldn't happen? Any error states to consider? |
| Existing Patterns | Are there similar features in the codebase to follow? |

**Exit condition:** Continue until the idea is clear OR user says "proceed" or "let's move on."

#### 1.3. Explore approaches

Propose **2-3 concrete approaches** with trade-offs. Lead with your recommendation and explain why.

**Guidelines:**

- **YAGNI ruthlessly.** If an approach adds complexity for a hypothetical future need, call it out and lean toward the simpler option. The question is always: "Do we need this now, or are we guessing?"
- **Prefer boring patterns.** If the codebase already solves a similar problem, default to that pattern. Consistency beats cleverness.
- **Right-size the architecture.** Not every feature needs its own package. Not every screen needs a new state management controller. Match the solution to the actual complexity.

**Structure for Each Approach:**

```markdown
**[Approach Name]** <- [Is it recommended? Yes/No]

[2-3 sentence description of what this looks like in practice]

- Pros: [what's good]
- Cons: [what's not]
- Best when: [the circumstances where this wins]
```

Use **AskUserQuestion tool** to ask which approach the user prefers.

#### 1.4. Set up workspace

Before writing any files, ensure the session is not on the base branch:

- Run `git rev-parse --abbrev-ref HEAD`. If the current branch is a base branch (`main`, `master`, or `develop`), use **AskUserQuestion** to offer creating a feature branch — `git checkout -b <type>/<kebab-topic>`, name under 60 characters — before writing. If already on a feature branch, continue without prompting.

### 2. Capture the design document

Write a brainstorm document to `docs/brainstorm/YYYY-MM-DD-<kebab-case-topic>-brainstorm-doc.md`.

Ensure `docs/brainstorm/` directory exists before writing.

Use the [brainstorm template](references/template.md) as the document structure.

### 3. Handoff

Use **AskUserQuestion tool** to consider next steps:

**Question**: "Brainstorm complete! What would you like to do next?"

**Options:**
1. **Clear context and plan (Recommended)**: clear context for a fresh start, then plan
2. **Continue with planning**: run the `/plan` skill to create a detailed implementation plan
3. **Review and refine approach:** improve the document using structured review
4. **Done for now**: brainstorm complete. To start planning later: `/plan`

**If the user selects "Clear context and plan"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path. Then stop.

**If the user selects "Review and refine approach"** then apply the @refine-approach skill to the document.

When `refine-approach` is complete, present these options:

1. **Clear context and plan (Recommended)**: clear context for a fresh start, then plan
2. **Move to planning**: run the `/plan` skill to create a detailed implementation plan
3. **Done for now**: ideation complete. To start planning later: `/plan`

**If the user selects "Clear context and plan"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path. Then stop.

## Output Summary

When complete, display:

```md
Brainstorm complete!

Document: docs/brainstorm/YYYY-MM-DD-<kebab-case-topic>-brainstorm-doc.md

Key decisions:
- [Decision 1]
- [Decision 2]
```

## Key Principles

- **One question at a time** - Don't overwhelm with multiple questions
- **Multiple choice preferred** - Easier to answer than open-ended when possible
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
- **Explore alternatives** - Always propose 2-3 approaches before settling
- **Incremental validation** - Present design in sections, validate each
- **Be flexible** - Go back and clarify when something doesn't make sense

## Important Guidelines

**DO NOT CODE!** Just explore and document decisions.