/brainstorm — Clarify Goals Before Planning
Purpose: Separate WHAT from HOW. Explore the problem space before committing to a solution.
Four phases:
- Assess clarity — Is the goal specific enough?
- Understand idea — What problem, who benefits, what exists?
- Explore approaches — Generate options, compare tradeoffs
- Capture design — Write structured output for
/plan
Quick Start
/brainstorm "add user authentication" # full 4-phase process
/brainstorm # prompts for goal
Execution Steps
Phase 1: Assess Clarity
If the user provided a goal string, evaluate it. Otherwise prompt for one.
Use AskUserQuestion with options to gauge clarity:
- clear — Goal is specific and actionable (e.g., "add JWT auth to the API")
- vague — Goal exists but needs narrowing (e.g., "improve security")
- exploring — No firm goal yet, just a direction (e.g., "something with auth")
If vague or exploring, ask follow-up questions to sharpen the goal before proceeding. Do NOT move to Phase 2 until you have a concrete problem statement (one sentence, testable).
Phase 2: Understand the Idea
Answer these questions (use codebase exploration as needed):
- What problem does this solve? — State the pain point in concrete terms.
- Who benefits? — End users, developers, operators, CI pipeline?
- What exists today? — Current state, prior art in the codebase, adjacent systems.
- What constraints matter? — Performance, compatibility, security, timeline.
Summarize findings before moving on. If anything is unclear, ask the user.
Phase 3: Explore Approaches
Generate 2-3 distinct approaches. For each:
- Name — Short label (e.g., "JWT middleware", "OAuth proxy", "Session cookies")
- How it works — 2-3 sentences
- Pros — What it gets right
- Cons — What it gets wrong or defers
- Effort — Rough scope (small / medium / large)
Present the comparison and use AskUserQuestion to let the user pick an approach or request a hybrid.
Phase 4: Capture Design
Generate a date slug: YYYY-MM-DD-<goal-slug> (lowercase, hyphens, no spaces).
Write the output file to .agents/brainstorm/YYYY-MM-DD-<slug>.md:
---
id: brainstorm-YYYY-MM-DD-<goal-slug>
type: brainstorm
date: YYYY-MM-DD
---
# Brainstorm: <Goal>
## Problem Statement
## Approaches Considered
## Selected Approach
## Open Questions
## Next Step: /plan
All five sections must be populated. The "Next Step" section should contain a concrete /plan invocation suggestion with the selected approach as context.
Create the .agents/brainstorm/ directory if it does not exist.
Termination
Phase 4 output written = done. No further phases, no loops.
Validation
After writing the output file, verify:
- File exists at the expected path
- All 5 sections (
Problem Statement,Approaches Considered,Selected Approach,Open Questions,Next Step: /plan) are present and non-empty
Report the file path to the user.
Examples
Example 1: Specific goal
User: /brainstorm "add rate limiting to the API"
Phase 1: Goal is clear — add rate limiting to the API.
Phase 2: Problem is uncontrolled request volume causing timeouts.
Benefits operators and end users. No rate limiting exists today.
Phase 3: Three approaches — token bucket middleware, API gateway,
per-route decorators. User picks token bucket.
Phase 4: Writes .agents/brainstorm/2026-02-17-rate-limiting.md
Example 2: Vague goal
User: /brainstorm "improve performance"
Phase 1: Goal is vague. Asks: "Which part? API response times,
build speed, database queries, or something else?"
User says: "API response times on the search endpoint."
Phase 2: Investigates search endpoint, finds N+1 queries.
Phase 3: Approaches — query optimization, caching layer, pagination.
Phase 4: Writes .agents/brainstorm/2026-02-17-search-performance.md
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| Brainstorm loops in Phase 1 without advancing | Goal remains too vague after follow-up questions | Provide a concrete, testable problem statement (e.g., "reduce API search latency below 200ms" instead of "improve performance"). |
| Output file missing one or more required sections | Phase 4 was interrupted or the skill terminated early | Re-run /brainstorm with the same goal; verify all 5 sections (Problem Statement, Approaches Considered, Selected Approach, Open Questions, Next Step: /plan) are present in the output. |
.agents/brainstorm/ directory not created | The skill could not create the directory (permissions or path issue) | Manually create it with mkdir -p .agents/brainstorm and re-run. |
/plan invocation in "Next Step" section is generic or incomplete | The selected approach was not specific enough to generate a concrete plan command | Edit the output file to refine the selected approach, then craft a /plan invocation that includes the approach name and key constraints. |
| Brainstorm produces only one approach in Phase 3 | The problem space is narrow or the goal is overly constrained | Widen the goal slightly or explicitly ask for alternative approaches (e.g., "consider a caching approach and a query optimization approach"). |
See Also
- skills/plan/SKILL.md — Decompose the selected approach into actionable issues