name: brainstorming description: > [STATUS: review] [CONFIDENCE: high] [REVIEWED: 2026-03-13] USE when user asks about architecture, design, or alternatives. MUST USE before multi-file changes requiring design decisions. Triggers: how to best, what are the options, let's think, design, brainstorm, alternatives, trade-offs, architecture, approach. ESPECIALLY when tempted to jump straight to code without design.

Skill: Socratic Design Brainstorming

When to Load

• New feature / module without a clear specification
• Architectural decision with non-obvious trade-offs
• User says "let's think", "how to best do this", "what are the options"

Principle

One question at a time. 2-3 alternatives with trade-offs. Hard gate: "design approved" before code.

Phase 0: Deep Interview (Ambiguity Gating)

Goal: block premature design when the problem space is still unclear.

Ambiguity Score

Evaluate four dimensions before any design work:

Score each 0–1. ambiguity = 1 − Σ(score × weight).

Protocol

• If ambiguity > 0.20: ask ONE question targeting the weakest dimension → wait → re-score.
• Repeat until ambiguity ≤ 0.20 or 3 rounds reached.
• After 3 rounds: proceed with assumptions stated explicitly.

Hard Rules

1. Explore codebase FIRST — read code/context before asking anything.
2. Never ask more than 1 open-ended question at a time. Multiple enumerable choices (pick a stack, pick a scope tier, yes/no on a tradeoff) may be clustered into a single AskUserQuestion call instead of separate turns — clustering applies to closed-choice questions, not to open framing questions.
3. Max 3 rounds — then state assumptions and move forward.
4. If goal clarity scores near 0 (the user has "something" in mind but can't yet state it), show 2-3 concrete example scenarios from this project's domain before the first question — a vague "what do you want" gets a vague answer; "here's what this could look like: A, B, C — which is closer, or something else?" gives the user something to react to. Skip this when goal clarity is merely low-but-nonzero — examples anchor answers unnecessarily when the user already has real direction, narrowing them toward the examples shown (source: launch-your-agent, Anthropic reference skill).

4 Phases

Phase 1: Problem Framing

Goal: make sure we are solving the right problem.

• Ask 1 question: "What specific problem are we solving? Who is the user and what will they get?"
• Wait for the answer. Do not jump to a solution.
• Restate the problem in 1 sentence for confirmation.

Phase 2: Constraint Discovery

Goal: identify constraints BEFORE generating solutions.

Check from code/context (do NOT ask what can be found out):

• Existing interfaces and contracts
• Dependencies that cannot be changed
• Performance/security requirements

Ask only what is NOT visible from the code:

• "Is there a deadline or budget constraint?"
• "Is this MVP or production-grade?"

Credential deferral: if the design will eventually need a secret/credential (API key, OAuth token, webhook URL) that isn't available right now, don't stall the whole design on it. Do every piece of design and staging work that doesn't need the credential first, then name exactly what's needed and exactly where to get it in one line ("you'll need a Slack webhook — create one at api.slack.com/apps → Incoming Webhooks"), so the user can fetch it in parallel while the rest proceeds. Never let "we're missing a credential" block work that doesn't actually depend on it.

Phase 3: Solution Exploration

Goal: 2-3 options with explicit trade-offs.

Format for each option:

### Option A: [name]
- Summary: [1-2 sentences]
- Pros: [specific]
- Cons: [specific]
- Effort: [low/medium/high]
- When to choose: [context]

Rules:

• Minimum 2, maximum 3 options (more = decision paralysis)
• One option is always the simplest (80/20)
• If there is a clear best option — say so directly, do not pretend to be neutral
• Show what is lost with each choice, not only what is gained

Phase 4: Design Decision

Goal: lock in the decision before code.

After an option is chosen:

1. Confirm: "Summary: we choose [option] because [reason]. Correct?"
2. Wait for an explicit "yes" / "approved" / "do it"
3. Record the decision in decisions.md (if architectural)
4. Hard gate: do NOT start coding before confirmation

Anti-patterns

Workflow Integration

• Plan-First Protocol: brainstorming = Design phase between Explore and Plan
• Scope Guard: if brainstorming goes beyond MVP — call scope-guard
• Architect agent: for complex architectural brainstorming — delegate to architect

Gotchas

• Always explore codebase BEFORE asking questions — context before interview
• If ambiguity score stays >20% after 3 rounds — proceed with assumptions stated explicitly