| 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?"
- Create project first (Recommended) — output instructions to run
/create, open the new folder, then /brainstorm <description> in that workspace. Then stop.
- 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:
- Clear context and plan (Recommended): clear context for a fresh start, then plan
- Continue with planning: run the
/plan skill to create a detailed implementation plan
- Review and refine approach: improve the document using structured review
- 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:
- Clear context and plan (Recommended): clear context for a fresh start, then plan
- Move to planning: run the
/plan skill to create a detailed implementation plan
- 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.
