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.

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.

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:

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

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.