/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-
id : brainstorm - YYYY - MM - DD - <goal - slug
type : brainstorm date : YYYY - MM - DD
Brainstorm:
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