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

$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 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 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 for /plan with the actual brainstorm doc path. Then stop.

Output Summary

When complete, display:

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.