/brainstorm

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

**[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 compl