brainstorm

name	brainstorm
description	Structured pre-planning research. Explores codebase, asks clarifying questions, and produces a brainstorm output file for /plan-feature input.
allowed-tools	Bash, Read, Glob, Grep, Task, AskUserQuestion, WebSearch, WebFetch
argument-hint	<topic>

Brainstorm: Pre-Planning Research

Objective

Run structured research BEFORE creating an implementation plan. Explore the codebase, ask the right questions, research options, and produce a brainstorm document that feeds into /plan-feature.

---

When to Use

• Before /plan-feature for complex features
• When requirements are unclear
• When multiple approaches are possible
• When you need to understand existing patterns before designing

---

Process

1. Define the Topic

Parse the argument as the brainstorm topic:

/brainstorm auth improvements
/brainstorm rate limiting strategy
/brainstorm convex schema redesign

2. Explore Current State

Before asking questions, gather context:

# What exists related to the topic?
# Search codebase for relevant code
# Read related reference docs
# Check for prior brainstorms/reviews on this topic

Check prior work:

ls .agents/brainstorms/ | grep -i "{topic keywords}"
ls .agents/reviews/ | grep -i "{topic keywords}"
ls .agents/plans/ | grep -i "{topic keywords}"

3. Ask Clarifying Questions

Use AskUserQuestion to understand intent and constraints:

Question Categories:

Category	Example Questions
Scope	"Should this cover all API routes or just the new ones?"
Constraints	"Any third-party libraries we should avoid?"
Priority	"Is this for the pilot customer or all customers?"
Timeline	"Is this blocking the next deploy?"
Approach	"Do you prefer X approach or Y approach?"

Rules:

• Ask 2-4 focused questions max (not a survey)
• Questions should be informed by what you found in the codebase
• Offer concrete options where possible (not open-ended)

4. Research Options

Based on answers, research approaches:

• Codebase patterns: How does the project already solve similar problems?
• Reference docs: What do .claude/reference/ docs say about this area?
• External research: Use WebSearch for framework-specific best practices
• Trade-offs: Document pros/cons of each approach

5. Produce Brainstorm Document

Write the output to:

.agents/brainstorms/YYYY-MM-DD-{topic-slug}.md

Document Template:

# Brainstorm: {Topic}

**Date:** YYYY-MM-DD
**Author:** Agent + {developer name}
**Status:** Complete -- Ready for /plan-feature

---

## Context

{What prompted this brainstorm. Link to Linear ticket if applicable.}

## Current State

{What exists today. Code references with file:line format.}

## Requirements (from Discussion)

{Answers from the clarifying questions.}

---

## Options Explored

### Option A: {Name}

**How:** {Description}
**Pros:** {List}
**Cons:** {List}
**Effort:** {S/M/L}
**Files touched:** {List}

### Option B: {Name}

**How:** {Description}
**Pros:** {List}
**Cons:** {List}
**Effort:** {S/M/L}
**Files touched:** {List}

---

## Recommendation

**Go with Option {X}** because {reason}.

{If no clear winner, explain trade-offs and let user decide.}

---

## Key Decisions Needed

- [ ] {Decision 1}
- [ ] {Decision 2}

---

## References

- {Link to relevant reference docs}
- {Link to relevant code}
- {External resources}

---

## Next Step

Run `/plan-feature {topic}` using this brainstorm as input.

6. Present Summary

After writing the document, show a compact summary:

BRAINSTORM COMPLETE
----------------------------------------------------------------------

File: .agents/brainstorms/YYYY-MM-DD-{topic}.md

Topic:          {topic}
Options:        {N} explored
Recommendation: Option {X} -- {one-line reason}

Decisions needed: {N}

Next: /plan-feature {topic}
----------------------------------------------------------------------

---

Examples

Simple Brainstorm

/brainstorm rate limiting

Explores rate limiting options, asks about scope, produces recommendation.

Complex Brainstorm

/brainstorm multi-tenant auth redesign

Deep research into current auth, explores BetterAuth patterns, researches alternatives.

---

Integration

/brainstorm {topic}     -- Research and explore options
    |
    v
/plan-feature {topic}   -- Design implementation plan (uses brainstorm as input)
    |
    v
/execute {plan}          -- Implement the plan
    |
    v
/review                  -- Validate the implementation

The brainstorm document is automatically discovered by /plan-feature when the topic matches.