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.

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.

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: "Describe the feature or problem you want to brainstorm. What's the core pain point it addresses, and what's still ambiguous to you?",
    header: "Feature Frame",
    options: [
      { label: "UX / user-facing surface is unclear", description: "You know what you want to build but not how it should work for the user." },
      { label: "Scope / boundaries are unclear", description: "You're not sure how much to build, or where one feature ends and another begins." },
      { label: "Multiple approaches exist — need to 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.

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 correctly in production?

AUQ format rules for every round:

• Present 2-4 options; Option 1 is ALWAYS marked (Recommended)
• Each option has a description with a concrete pro/con (one sentence each)
• Include an Other / describe below option when free-form input makes sense
• multiSelect: false unless the question is genuinely multi-select (e.g., integration targets)

Example round (adapt to the actual feature):

AskUserQuestion({
  questions: [{
    question: "Who is the primary user of this feature, and how do they trigger it?",
    header: "User Surface — Round 2",
    options: [
      { label: "Authenticated user via UI action (Recommended)", description: "Pro: fits existing session model. Con: requires UI component work." },
      { label: "Automated trigger (webhook, cron, event)", description: "Pro: no manual user step. Con: harder to debug and test." },
      { label: "Admin-only operation", description: "Pro: simpler access control. Con: limits who can self-serve." },
      { label: "Other / describe below", description: "Describe the trigger mechanism." }
    ],
    multiSelect: false
  }]
})

After each round, record the answer in a running summary:

## Design Answers (Round N/M)
- User surface: [answer]
- Data shape: [answer]
- ...

Present this summary in plain text between rounds so the user can catch any misunderstanding.

Phase 3: Synthesize Approaches

Once the dialogue has enough signal, synthesize 2-3 concrete implementation approaches and present them via AUQ:

AskUserQuestion({
  questions: [{
    question: "Based on your answers, here are the viable approaches. Which fits best?",
    header: "Design Approach",
    options: [
      { label: "Approach A — [1-sentence summary] (Recommended)", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." },
      { label: "Approach B — [1-sentence summary]", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." },
      { label: "Approach C — [1-sentence summary]", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." }
    ],
    multiSelect: false
  }]
})

Mark the approach that best balances user value, reversibility, and smallest scope as (Recommended). State your reasoning in one sentence before the AUQ call (plain text, not another question).

If the user selects "Other" or asks for modifications, incorporate the feedback and re-present before proceeding.

Phase 4: Write Spec

Generate today's date via date +%Y-%m-%d. Derive <slug> from the feature name (lowercase, hyphens, no special characters). Ensure the target directory exists:

mkdir -p docs/specs

Write docs/specs/YYYY-MM-DD-<slug>-design.md with the following sections:

# [Feature Name] — Design Spec

> Generated by /brainstorm on YYYY-MM-DD. Status: draft.

## Problem

[1-3 sentences: what pain point does this address, and for whom?]

## Chosen Approach

[Name of the selected approach from Phase 3. 2-4 sentences describing the design decision.]

## Trade-offs Accepted

| Trade-off | Rationale |
|-----------|-----------|
| [Pro accepted] | [Why this matters] |
| [Con accepted] | [Why it's tolerable] |

## Acceptance Criteria (EARS) [optional]

> Optional companion — translates the chosen-approach behaviour into EARS-shaped statements (IEC/IEEE 29148, canonical 5 patterns from Mavin et al.). Leave blank if narrative trade-offs suffice. Authors who include this section make their spec natively consumable by `/write-executable-plan` for 1:1 vitest stub generation.

### Ubiquitous (always-true invariants)
- The {{system}} shall {{response}}.

### State-driven (While …)
- While {{precondition}}, the {{system}} shall {{response}}.

### Event-driven (When …)
- When {{trigger}}, the {{system}} shall {{response}}.

### Optional feature (Where …)
- Where {{feature enabled}}, the {{system}} shall {{response}}.

### Unwanted behaviour (If … then …)
- If {{unwanted condition}}, then the {{system}} shall {{response}}.

## Open Questions

- [Genuine unresolved question that needs more information or runtime data]
-