---
name: brainstorm
description: "Explore the solution space when the path isn't obvious - invent options, stress-test them, pick one. Use for architecture decisions, design tradeoffs, and when the user asks 'how should I approach X?'. Default produces a decision brief; pass `--quick` for chat-only, `--deep` for multi-round adversarial debate with full design doc. Do not use when want is unconfirmed (vd:interview), when the user says 'grill me' (vd:interview --grill), or when the deciding will not fit one session (vd:interview --wayfinder)."
license: MIT
argument-hint: "[topic or problem] [--quick | --deep]"
metadata:
  author: vanducng
  version: "1.4.0"
---

# Brainstorm

Brainstorm is **solution-space exploration**. You may end up recommending a known pattern, but the job is to surface paths the user hasn't considered, then converge. It does not own grilling - that is `vd:interview --grill`. After the user picks an option, grill remaining load-bearing decisions through that skill rather than inventing a second interview loop here.

## Hard rules

1. **No code, no scaffolding, no file edits to source.** Only the brief gets written. If the user pushes for implementation, point them at `vd:plan` or `vd:cook`.
2. **Minimum 3 genuinely divergent options.** If all your options share the same architectural assumption (e.g. all are "different ORMs"), you haven't diverged - invent one that violates the shared assumption (e.g. "no ORM, raw SQL").
3. **Steel-man before strawman.** For each option write the *strongest* case first. If you can't argue for it convincingly, you don't understand it yet.
4. **Brutal honesty.** Name dealbreakers, hidden costs, ops burden, lock-in, hiring market, debugging pain. No marketing language. No symmetric "it's all tradeoffs" hedging - pick one.
5. **Decomposition first, depth second.** If the request spans 3+ independent subsystems, stop and decompose before any deep-dive.

## Modes

| Mode | When | Output |
|---|---|---|
| `--quick` | Single decision, low stakes, user wants chat | Verbal recommendation only - no file written |
| **default** | Standard architecture/design decision | Decision brief saved to disk |
| `--deep` | High-stakes, multi-component, irreversible | Full design doc with red-team round, decomposition, migration paths |

Detect mode from the argument or the user's language ("just a quick take" → `--quick`, "this is going to production" / "we need to get this right" → `--deep`). Announce the mode in your first message.

## Phase 1 - Frame

Before generating options, write down (in your reply, briefly):

- **The decision** - one sentence, in the user's words, restated precisely
- **Constraints** - what's fixed (language, team, deadline, existing systems, cost ceiling)
- **Success criteria** - what makes a chosen option "good" for *this* user
- **Want vs should-want** - the stated ask is sometimes a guess at the real need. Probe once: "you asked for X - is the underlying goal Y?" A wrong-framed problem produces three right answers to the wrong question.
- **Out of scope** - name what this decision explicitly is *not* solving, so options don't sprawl. Carry these into the brief's Non-goals.
- **Reversibility** - how expensive to switch later. High reversibility → bias toward speed. Low reversibility → bias toward depth.

If the *want* is unclear (missing who / why / success / constraint / out of scope) → **stop and run `vd:interview`**. Generating 3 options for an unconfirmed outcome is the wrong skill. Brainstorm starts after intent is confirmed.

If only a *constraint* or success criterion is fuzzy but the outcome is known, **ask before generating options**. Generating 3 wrong-shaped options because you assumed the constraints wastes the whole session.

**How to ask:** one clarifying question per message. Prefer multiple choice (A/B/C) over open-ended when the answer space is bounded - it's faster to answer and surfaces hidden assumptions. Save open-ended for "what does success look like?" style framing. Don't stack 4 questions in one reply.

### Scope check (mandatory)

If the request describes 3+ independent concerns ("build platform with auth + billing + analytics + chat") **stop**. Do not brainstorm. Reply:

> This spans N independent subsystems. Each deserves its own brainstorm. Suggested decomposition: [A, B, C]. Suggested order: [reason]. Pick one to start.

Do not deepen until the user picks one. This is the single most common failure mode of brainstorming sessions. When the decomposition itself spans more sessions than one brainstorm-per-part can carry - many interdependent decisions, weeks of fog - offer `vd:interview --wayfinder` to chart the whole space as a decision map instead.

## Phase 2 - Diverge

Generate at least **3 genuinely different options**. Force divergence:

- **Option A** - the obvious one (what most engineers would reach for)
- **Option B** - a different architectural shape (different boundary, different layer, different paradigm)
- **Option C** - the one that violates a shared assumption of A and B (no DB, no service, build vs buy, manual vs automated, do nothing)

If you find yourself generating "X with Postgres / X with MySQL / X with SQLite" - that's one option, not three. Restart.

**Name the lens behind each option** so divergence is deliberate, not luck. Pick a different generative lens per option - say which:

- **Inversion** - solve the opposite ("don't store it" vs "store it better").
- **Constraint removal** - drop a constraint everyone assumed ("what if cost/latency/consistency didn't matter here?").
- **Audience shift** - design for a different user (the operator, not the end user; the future maintainer).
- **Combination** - fuse two existing approaches into one.
- **Simplification** - the do-less / do-nothing option.
- **10x** - what would you build if this had to handle 10x the scale/users/data.
- **Expert lens** - how would a {distributed-systems / security / data} specialist frame it.

For a deeper toolkit (SCAMPER, How-Might-We, JTBD, pre-mortem), see [`references/ideation-frameworks.md`](references/ideation-frameworks.md).

Where helpful, pull in proven patterns: search the web (`WebSearch`), read library docs, scan the codebase. Don't invent in a vacuum when the wheel exists. But also don't *only* surface known options - the user could have searched too.

**For visual brainstorming** (UI layouts, page/dashboard structure, comparing visual designs): produce a **visual draft** alongside text options - a single static HTML page rendering A/B/C panels in the browser, so the user can react to shapes, not just words. Full procedure, save paths, CSS vocabulary, and specialist handoff (`vd:opendesign` / `vd:diagram` / `vd:excalidraw`): [`references/visual-draft.md`](references/visual-draft.md). The brief itself stays text-only - visual drafts are intermediate artifacts.

## Phase 3 - Stress-test (red team)

For each option, fill in:

| Field | What goes here |
|---|---|
| **Pitch** | One sentence steel-man - the strongest case for this option |
| **How it works** | 2-4 sentences - concrete enough that the reader could sketch it |
| **Strengths** | What this is genuinely good at - not generic ("it's simple"), specific ("you skip the migration step entirely") |
| **Weaknesses** | What hurts in production, on month 6, when the team grows |
| **Dealbreaker check** | One concrete scenario where this option *fails* for this user's context |
| **Hidden cost** | Ops burden, hiring market, debugging pain, vendor lock-in, license, on-call load |
| **Reversibility** | Cost to switch off this option in 12 months |

In `--deep` mode: also produce a **failure-mode catalog** per option (what breaks at scale, under load, under attack, when the team turns over).

## Phase 4 - Converge

Don't punt. Pick one. State:

- **Recommendation:** Option X.
- **Why it wins:** One paragraph, grounded in the user's *actual* constraints from Phase 1.
- **Runner-up:** Option Y wins if {specific condition flips} - name the condition.
- **Avoid:** Option Z because {dealbreaker}. Or "no option avoids the user's biggest risk - here's how to mitigate it regardless."

If you genuinely cannot pick because a constraint is missing, identify the missing constraint and ask one targeted question. Don't hide indecision behind "it depends."

## Phase 5 - Brief

### Where to save

**Feature-first repos - claim a feature first.** If the hook context shows `Feature: none` (paths resolve under `_global/scratch/`), run `workbench new <slug>` (kebab summary of the task) before writing, then use the paths it prints - work lands in `features/<slug>/` instead of the shared scratch bin. Idempotent: skip when a feature is already active (a `feat/*` branch, an active plan, or a prior `workbench new`).

Write to the injected `Reports:` path. Filename: `brainstorm-{YYYYMMDD-HHMM}-{slug}.md`. `--quick` mode: skip the file. Verbal output only.

### Template (default mode)

```markdown
# Brainstorm: {Topic}

_Date: {YYYY-MM-DD} · Mode: default_

## TL;DR
- **Recommendation:** {Option X}, because {one sentence rooted in user's constraints}.
- **Runner-up:** {Option Y} - wins when {specific condition}.
- **Avoid:** {Option Z} - {dealbreaker}.

## The Decision
The exact decision being made, restated in one sentence.

## Constraints & Success Criteria
- Constraint: {fixed thing}
- Constraint: {fixed thing}
- Success: {what "good" looks like for this user}
- Reversibility: {high | medium | low - and what that implies}

## Options

### Option A - {name}
- **Pitch:** {one-sentence steel-man}
- **How it works:** {2-4 sentences, concrete}
- **Strengths:** {specific, not generic}
- **Weaknesses:** {what hurts in month 6}
- **Dealbreaker scenario:** {one concrete failure case}
- **Hidden cost:** {ops, hiring, lock-in, debugging}
- **Reversibility:** {cost to switch off}

### Option B - {name}
(same shape)

### Option C - {name}
(same shape)

## Comparison

| Criterion | A | B | C |
|---|---|---|---|
| Time to first ship | … | … | … |
| Ops burden | … | … | … |
| Reversibility | … | … | … |
| Failure blast radius | … | … | … |
| {user-specific criterion} | … | … | … |

## Recommendation
The full case. Why X wins *given the user's constraints*. The condition under which the runner-up takes over. What we're explicitly trading away.

## Open Questions
What couldn't be answered without more input. What would change the recommendation.

## Next Step
- If user wants a plan: `vd:plan` with this brief as input
- If user wants to validate before committing: spike Option X for {time-box}
```

### Template additions for `--deep` mode

When `--deep` fans its research/red-team rounds out through the Workflow tool, keep each agent's output schema minimal - mark only truly-required fields `required`, avoid `additionalProperties: false`, and paste a one-line valid JSON example into every agent prompt (strict schemas fail ~74% of first attempts, then self-heal on costly retries).

Add these sections after **Recommendation**:

```markdown
## Red-Team Round
For each option, the strongest argument *against* it from a hostile reviewer's perspective. Then the rebuttal - or the concession.

## Failure-Mode Catalog
| Option | Failure | Trigger | Blast radius | Mitigation |
|---|---|---|---|---|
| … | … | … | … | … |

## Migration Paths
- From current state → Option X: cost, breaking changes, sequencing
- Same for runner-up (so the user sees the cost of being wrong)

## Decomposition (if applicable)
If the chosen option has independent sub-parts, list them in build order with rationale.
```

## Phase 6 - Self-review & handoff

### Self-review (mandatory before handoff)

After writing the brief, re-read it with fresh eyes and fix issues inline. No second pass - just fix and move on:

1. **Placeholder scan** - any `TBD`, `TODO`, `{...}` template stubs, or unfilled cells in the comparison table? Fill or remove.
2. **Internal consistency** - does the recommendation in TL;DR match the recommendation in the long section? Do the strengths/weaknesses contradict the dealbreaker scenario? Does the runner-up condition actually flip the decision?
3. **Scope check** - is this still one decision, or did it sprawl into 3? If it sprawled, decompose and write multiple briefs.
4. **Ambiguity check** - could any criterion or recommendation be read two ways? Pick one and make it explicit.
5. **Divergence check** - re-read the three options. If two share the same architectural assumption, you didn't diverge - regenerate the weakest one.

### User review gate

After self-review, surface the file with an openable location and stop. Do not auto-invoke `vd:plan`:

> Brief saved to `[brainstorm-topic.md](/absolute/path/to/brainstorm-topic.md)` (`file:///absolute/path/to/brainstorm-topic.md`). Recommendation: **{Option X}**, runner-up **{Option Y}** if {condition}. Please review and tell me if you want changes - or say "plan it" and I'll hand off to `vd:plan`.

If the decision is consequential and hard to reverse (datastore, framework, auth model, a public contract), offer to record it permanently: `vd:docs adr` writes an ADR under `docs/decisions/` capturing the why and the rejected alternatives. The brief is a working artifact; the ADR is the durable team-facing record.

If the user requests changes, edit the brief and re-run the self-review checklist before re-surfacing. Only invoke `vd:plan` after explicit approval.

**Read approval critically - not every "yes" is a real yes.** Watch for these and probe instead of proceeding:

- **Polite yes** - "sounds good" with no engagement on the tradeoffs. Ask which part resonated; a real yes can name why.
- **Tired yes** - agreeing to end the conversation after a long thread. Offer to pause rather than bank a fatigue decision.
- **Deferring yes** - "you're the expert, whatever you think." Push the one judgment call back to them; you can't own a constraint only they know.
- **Misunderstood yes** - agreeing to a different thing than you proposed. Restate the recommendation in one line and confirm it's the same picture.

A decision banked on a fake yes resurfaces as rework two phases later.

`--quick` mode skips Phase 6 entirely - verbal output only.

## Workflow position

**Typically follows:** `vd:interview` (confirmed want), `vd:scout` (after surveying the surface), `vd:debug` (when the diagnosis exposes a design decision worth re-deciding)

**Typically precedes:** `vd:plan` (for the chosen approach), or `vd:research` (if Phase 3 surfaced an unknown option that needs deep evaluation)

**Compares to:** `vd:interview` (extract want, no options) - when the outcome is unconfirmed, prefer `interview`. `vd:interview --grill` (walk an existing idea) - not a brainstorm mode. `vd:research` (known options, cited comparison) - when the user names options, prefer `research`; when the path is unclear, prefer `brainstorm`. `vd:interview --wayfinder` - when the deciding itself will not fit one session.