brainstorm

Brainstorm: Pre-Creation Design Exploration

Explore the problem space, clarify requirements, and converge on a design direction before creating issues. This skill produces a spec document — capturing intent, trade-offs, the chosen approach, and enough detail for both issue creation (/pm) and implementation planning (/cdt).

When to Use

Use this skill when:

• The work is ambiguous — user knows what they want but not how
• Multiple valid approaches exist and trade-offs need discussion
• Scope is unclear — could be one issue or an epic with sub-issues
• The problem domain is unfamiliar and needs exploration first
• A request is large enough that jumping straight to issue creation would produce a vague ticket

Do NOT use for:

• Clear, well-scoped bugs (go directly to /pm)
• Simple chores or dependency updates
• Work that already has a design document or spec

Hard Gate

<HARD-GATE> Do NOT invoke /pm, /cdt, create any GitHub issue, or take any implementation action until:

1. You have proposed approaches and the user has selected one
2. You have presented a spec document and the user has approved it

This applies to EVERY brainstorming session regardless of perceived simplicity. A spec can be short (5-10 lines for a simple feature), but it must exist and be approved. </HARD-GATE>

"This Is Too Simple To Need a Spec"

No. Every brainstorming session produces a spec. The spec scales with complexity:

• Simple feature: 5-10 lines covering approach, scope, and key decisions
• Medium feature: half a page with trade-off analysis and component breakdown
• Complex initiative: full spec with architecture, decomposition, and risk assessment

The cost of a 30-second review of a short spec is negligible. The cost of a poorly scoped issue that an agent executes in the wrong direction is significant.

Arguments

If the user provides arguments (e.g., /pm:brainstorm caching layer for API), treat the entire argument string as the initial topic. Use it to focus Step 1 context gathering and to skip obvious clarifications in Step 2. If no arguments are provided, start with an open-ended discovery in Step 2.

Workflow

1. Context → 2. Clarify → 3. Propose → 4. Converge → 5. Write Spec → 6. Self-Review → 7. User Review → 8. Transition

Step 1: Explore Context

Before asking any questions, gather context silently:

1. Project awareness: Read the project's README, CLAUDE.md, or similar docs to understand what this project does
2. Recent work: If the current directory is inside a Git work tree, run git log --oneline -20 to see recent direction. If not, skip this step silently.
3. Relevant code: If the user mentioned a specific area, use Glob and Grep to survey it
4. Existing issues: Check if gh is available and authenticated, then run gh issue list --limit 10 --state open to check for related work. If gh is not available or not authenticated, skip this step silently — it's informational, not blocking.
5. Visual workflow overview: If the visual-explainer:generate-web-diagram skill is available, invoke it to show the user an interactive workflow diagram — the 8 steps as a flowchart with the current step highlighted and the review loop (Step 7 → Step 5) shown as a feedback edge. This gives the user a visual map of the process they're about to go through. Skip this if visual-explainer is not installed.

Cross-project topics. If the user's topic is about a different project than the current working directory (e.g., they ask about their Express API while you're in a skills marketplace repo), acknowledge this in Step 2. You can still brainstorm effectively — use WebSearch to research the domain, ask the user for relevant file paths or architecture details, and note in the spec's "Files Affected" section that paths are assumed and should be verified. Do not fabricate file paths you cannot confirm.

Do NOT dump this research back at the user. Use it to ask smarter questions in Step 2.

Step 2: Clarify Intent

Ask clarifying questions to understand what the user actually wants. Follow these rules strictly:

One question per message. Never ask more than one question at a time. Wait for the answer before asking the next question. This forces depth — users give better answers to focused questions than to a wall of 5 questions at once.

Prefer multiple choice over open-ended. When possible, offer 2-4 concrete options rather than asking "what do you want?" Open-ended questions get vague answers; structured choices get decisions.

Use your context research. Frame questions using what you learned in Step 1. Instead of "what part of the codebase?" ask "I see the auth module uses JWT tokens in src/auth/ — is this about the token refresh flow or the login flow?"

Stop when you have enough. You need to understand:

• What problem is being solved (the "why")
• Who it's for (users, developers, ops)
• What success looks like (observable outcome)
• What's explicitly out of scope

Three to five questions is typical. Do not over-interrogate — if the user gives a rich initial description, you may only need one or two clarifications.

Step 3: Propose Approaches

Present 2-3 distinct approaches. For each approach, include:

1. Name — a short label (e.g., "Approach A: Event-driven pipeline")
2. How it works — 2-3 sentences describing the approach
3. Trade-offs — what you gain and what you give up
4. Complexity — rough effort level (small / medium / large)
5. Risk — what could go wrong or what's unknown

End with a recommendation — state which approach you'd pick and why. Do not be neutral. Take a position. The user can override, but fence-sitting wastes everyone's time.

Apply YAGNI ruthlessly. If an approach adds flexibility "in case we need it later," flag that as speculative complexity. Propose the simplest approach that solves the stated problem. If the user wants extensibility, they'll ask.

Visual comparison (optional, requires visual-explainer plugin). If the approaches involve architectural differences (data flow, component structure, system boundaries) and the visual-explainer:generate-web-diagram skill is available, invoke it to render a side-by-side comparison diagram. This is especially valuable for:

• Pipeline/workflow designs with different topologies
• Component architectures with different boundaries
• Data flow alternatives (push vs. pull, sync vs. async)

Do NOT generate visuals for trivial choices or when the text description is sufficient. Ask the user first: "Would a visual comparison of these approaches help?"

Use AskUserQuestion to let the user pick:

Question: "Which approach do you prefer?"
Options:
  - Approach A: [name] — [one-line summary]
  - Approach B: [name] — [one-line summary]
  - Approach C: [name] — [one-line summary]
  - None of these — let me describe what I want

Step 4: Converge on Design

With the chosen approach, flesh out the design. Present it in sections scaled to complexity:

For simple features (1 issue):

• Approach summary (2-3 sentences)
• Key decisions (bullet list)
• Scope boundary (in/out)

For medium features (2-3 issues):

• Approach summary
• Key decisions with rationale
• Component breakdown (what pieces need to change)
• Scope boundary
• Open questions (if any remain)

For complex initiatives (epic-level):

• Approach summary
• Architecture overview (components, data flow, interfaces)
• Decomposition into work units (each becomes an issue)
• Dependencies between units
• Scope boundary
• Risks and mitigations
• Open questions

Codebase exploration. Before presenting the design, explore the codebase for the chosen approach:

1. Use Glob and Grep to find files that will need modification
2. Use Read to understand existing patterns, interfaces, and conventions in the affected areas
3. Check for related work: existing TODOs, tests, similar implementations
4. Re