brainstorm

Files (4)

• SKILL.md
• comparison-template.html · assets/
• ideation-frameworks.md · references/
• visual-draft.md · references/

SKILL.md (first lines)

# 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}.

From vanducng/skills, MIT.

More from vanducng/skills