/brainstorm

name: brainstorm
description: Use when you have a feature idea but the scope or UX is still ambiguous — runs a lightweight Socratic design dialogue (3-5 AUQ rounds) and writes a spec markdown file. Use BEFORE /plan feature when product intent needs validation; skip to /plan feature when scope is already clear. HARD-GATE prevents any code work until the design is user-approved.
model: inherit
color: cyan
user-invocable: true
disable-model-invocation: true
argument-hint: "[topic-or-feature-slug]"
tools: Read, Grep, Glob, Bash, Write

Brainstorm Skill

> Lightweight Socratic design dialogue for per-feature exploration. Sibling to `/plan feature`, not a replacement. Produces `docs/specs/YYYY-MM-DD-<slug>-design.md` after the user approves an approach.

Invocation

The user invokes `/brainstorm` with arguments: **$ARGUMENTS**.

The optional argument is a topic or feature slug used in the spec filename (lowercase, hyphens, no special characters). If absent, the skill derives a slug from the user's Phase 1 answer.

Examples:

• `/brainstorm` — no slug; skill prompts for the problem in Phase 1
• `/brainstorm export-to-csv` — slug pre-set to `export-to-csv`
• `/brainstorm "user notification system"` — normalize to `user-notification-system`

The HARD-GATE in Phase 0 below prevents any Edit, Write (code), or Bash (implementation) call until the user approves the design in Phase 6 — the only Write permitted before approval is the spec file itself in Phase 4.

Soul Reference

Read `soul.md` in this skill directory before anything else. It defines WHO you are — a Design Facilitator who shapes vague ideas into approved designs through Socratic questioning. Every interaction in this skill should reflect that identity.

When to use

• A new feature is requested but the UX, product surface, or scope is still ambiguous
• The user wants design validation before committing to a full PRD
• Multiple plausible approaches exist and the trade-offs need to be surfaced first
• A "what should this look like?" question that would otherwise collapse into unfocused implementation work

When NOT to use

• Scope is already clear → use `/plan feature` directly
• A full project kickoff is needed → use `/plan new`
• A spec or PRD already exists → use `/plan feature` to formalize it
• Pure bug fixes or regressions → use `/debug` (issue #37) once shipped

Phase 0: Bootstrap Gate

Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If GATE_CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before returning here. If GATE_OPEN, continue.

<HARD-GATE> Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY brainstorm regardless of perceived simplicity.

There is no bypass. There is no exception for urgent requests, demo features, or spike work. The ONLY valid next action when the design is unapproved is presenting a design and waiting for user approval. </HARD-GATE>

Phase 1: Frame the Problem

Parse `$ARGUMENTS` for an optional topic or feature slug. The slug will be used in the spec filename. If absent, derive it from the user's Phase 1 answer.

Run a single AUQ to let the user characterize the problem in their own words:

AskUserQuestion({
  questions: [{
    question: "What do you want to brainstorm, and what is still unclear about it?",
    header: "Frame",
    options: [
      { label: "The user-facing surface", description: "You know what to build but not how it should work for the user." },
      { label: "Scope / boundaries", description: "You're not sure how much to build, or where one feature ends and another begins." },
      { label: "Several approaches — pick one", description: "You see 2-3 ways to solve this and aren't sure which is best." },
      { label: "Other / describe below", description: "Free-form: describe the ambiguity in the next prompt." }
    ],
    multiSelect: false
  }]
})

After the user responds, confirm your understanding with a 1-2 sentence summary before continuing.

Phase 2: Socratic Dialogue (3-5 AUQ rounds)

Run 3 to 5 AUQ rounds. Each round asks ONE question. Stop when the design space is sufficiently constrained — fewer rounds is better. Do NOT run more than 5 rounds; if still ambiguous after 5, recommend switching to `/plan feature`.

**Generate before narrowing — three-lens divergent pass (not a numbered round):** before the rounds below start narrowing the design space, generate divergently, once. Run three lenses in sequence, ~5 ideas each as terse bullets, no AUQ, no evaluation yet:

• **PM lens** — user value / outcome: what job does this do for the user, what's the smallest slice that delivers it?
• **Designer lens** — UX / interaction: how does the user encounter and trigger this, what does the surface look like?
• **Engineer lens** — feasibility / leverage: what's the cheapest lever that gets most of the value, what existing system can this ride on?

Then converge: carry the 2-3 most viable ideas forward as input to the rounds below, and note the rest as explicitly discarded (one line each — "considered X, discarded because Y"). Present both the three-lens listing and the convergence as plain text before Round 1. This pass consumes none of the 3-5 counted AUQ rounds — it's silent generation, not dialogue.

**Round topics (select the most relevant; do not ask redundant questions):**

1. **User-facing surface** — who triggers this feature, what do they see, what action do they take? 2. **Data shape** — what data is created, read, updated, or deleted? Any persistence, sync, or external service involved? 3. **Integration points** — what existing systems, APIs, or modules does this touch? What must NOT change? 4. **Risk / reversibility** — what could go wrong? Is this easy to roll back if it doesn't work? 5. **Success criteria** — how will you know this feature is working cor