stevengonsalvez/brainstorm

Brainstorm idea: $ARGUMENTS. Output is an approved spec doc, not code. Brainstorm is the orchestrator; /interview runs the actual Q&A.

<HARD-GATE> Do NOT write code, scaffold a project, run install/build commands, or invoke any implementation skill (`/plan`, `/implement`, `/plan-tdd`, framework codegen) until a written spec exists in `.agents/specs/` AND the user has explicitly approved it via the user-review gate (Step 10). Once both conditions are satisfied, Step 12 (`/plan` handoff) is the intended terminal action. Applies to every project regardless of perceived simplicity. </HARD-GATE>

Anti-pattern: "too simple to need a design"

Every brainstorm produces a spec. Todo list, single-function util, config change - all of them. "Simple" is where unexamined assumptions bite hardest. Spec can be 10 lines for trivial work, but it must exist and be approved.

<!-- recall:begin -->

Step 1: Prior-art check (MANDATORY)

Recall prior learnings from the global knowledge base before brainstorming so we don't re-decide something already captured:

uv run "{{HOME_TOOL_DIR}}/skills/recall/scripts/recall.py" \
  "<QUERY>" \
  --limit 5 --format markdown

Query construction: topic + constraint hints (e.g. "caching strategy mobile offline").

What to do with results:

• If a returned learning names a constraint, anti-pattern, or prior decision directly relevant - surface it to the user BEFORE proceeding.
• If nothing relevant returns - proceed silently.
• Never block on recall failure. Empty output / non-zero exit = "no prior art found", not error.

<!-- recall:end -->

Process flow

┌──────────────┐   ┌─────────────┐   ┌──────────────┐   ┌──────────────┐
│ Recall +     │──▶│ Detect      │──▶│ Scaffold     │──▶│ INVOKE       │
│ Project scan │   │ subject type│   │ topic-stub   │   │ /interview   │
└──────────────┘   └─────────────┘   └──────────────┘   └──────┬───────┘
                                                               │
                            /interview runs the Q&A,           │
                            uses ASCII previews from stub,     │
                            writes <stub>-spec.md              │
                                                               ▼
┌──────────────┐   ┌─────────────┐   ┌──────────────┐   ┌──────────────┐
│ /plan        │◀──│ User review │◀──│ Self-review  │◀──│ Read back    │
│ handoff      │   │ gate        │   │ spec         │   │ spec from    │
│              │   │             │   │              │   │ /interview   │
└──────────────┘   └─────────────┘   └──────────────┘   └──────────────┘

Terminal state = /plan invocation. Never invoke /implement or framework codegen direct from brainstorm.

Division of labour

| Skill | Role | |---------------|-----------------------------------------------------------------| | /brainstorm | Recall, project context, subject-type detection, stub scaffolding with ASCII previews, self-review, user-review gate, /plan handoff | | /interview | The actual iterative AskUserQuestion-based Q&A loop, populating the spec file |

Brainstorm is the orchestration layer. It writes one rich stub file, hands off, reads the result. The interview skill is the Q&A engine.

Checklist (track via TaskCreate)

1. Recall prior learnings - Step 1 below
2. Scan project context - files, docs, recent commits, existing patterns
3. Decompose if too large - flag and split before refining details
4. Detect subject type - drives which ASCII preview library slice to embed
5. Pre-stub clarifier (optional, ≤ 1 question) - only if subject type / scope is ambiguous
6. Scaffold topic-stub.md - .agents/specs/YYYY-MM-DD-<topic>-stub.md with hypotheses, ASCII slice, instructions, output template
7. Invoke /interview <stub-path> via Skill tool - it runs the Q&A and writes <stub>-spec.md
8. Read back spec - at .agents/specs/YYYY-MM-DD-<topic>-stub-spec.md
9. Self-review spec - placeholder / contradiction / ambiguity / scope / YAGNI sweep
10. User-review gate - explicit approval before handoff
11. Rename + commit - move final spec to .agents/specs/YYYY-MM-DD-<topic>.md
12. Handoff - invoke /plan skill with spec path

Step 2: Project context

Before drafting the stub:

• git log --oneline -20 for recent direction
• ls repo root + relevant subdirs
• Read existing docs/, README.md, AGENTS.md, CLAUDE.md
• Note existing patterns to follow

Step 3: Decompose check

Before refining details, assess scope. If the request names multiple independent subsystems ("platform with chat + file storage + billing + analytics"), STOP and decompose:

┌─ Original idea ────────────────────┐
│ "Build platform with X, Y, Z"      │
└─────────────────┬──────────────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
    ┌───────┐ ┌───────┐ ┌───────┐
    │ Sub-X │ │ Sub-Y │ │ Sub-Z │
    └───────┘ └───────┘ └───────┘
   spec→plan  spec→plan  spec→plan
   (each runs its own brainstorm cycle)

Pick the first sub-project. Brainstorm THAT. Other sub-projects each get their own /brainstorm cycle later.

Step 4: Detect subject type

Infer from $ARGUMENTS + project context. If ambiguous, ask ONE AskUserQuestion (Step 5). Often a single brainstorm spans 2-3 types (e.g. API + data model + CLI) - include the ASCII library slice for each.

| Subject | Preview shape | |-------------|------------------------------------------------| | UI (web/mobile) | ASCII wireframe (header / sections / buttons) | | TUI | ASCII screen mock (panes / status bar / keys) | | API | endpoint + request/response JSON snippet | | Data model | entity box + relationship arrows | | Architecture | component box + dataflow arrows | | CLI | command syntax + sample stdout | | Config | YAML/JSON snippet | | State machine | state node + transition arrows | | Pure concept | (no preview - text description only) |

Step 5: Pre-stub clarifier (optional, ≤ 1 question)

Only if subject type or core scope is unclear. Use AskUserQuestion. Examples:

• "What kind of artifact is this?" with options { Web UI, Mobile UI, TUI, API, CLI, library, mixed }
• "Hard constraint?" with options { has deadline, no constraints, needs perf target }

If you have enough context from $ARGUMENTS + project scan, skip this step and go straight to stub scaffolding. The point is to give /interview enough to run with, not to do its job for it.

Step 6: Scaffold the topic-stub

Read the ASCII library first: {{HOME_TOOL_DIR}}/skills/brainstorm/assets/ascii-library.md. It has 8 subject-keyed sections (UI / TUI / API / Data model / Architecture / CLI / Config / State machine). Copy the matching slice(s) into the stub's ## ASCII preview library section.

Resolve every <placeholder> from $ARGUMENTS + Step 2 context BEFORE writing the file. The on-disk stub must contain no angle-bracket placeholders, no TBD, no TODO (per Stevie's <paste_ready_artifacts> rule). A placeholder-laden stub wastes /interview's first round on re-derivation.

Write to .agents/specs/YYYY-MM-DD-<topic-slug>-stub.md. The stub IS the contract with /interview - it must contain EXACTLY these headings (interview matches them exactly):

• ## Idea
• ## Project context (inferred)
• ## Subject type(s)
• ## Initial hypotheses
• ## ASCII preview library
• ## For /interview
• ## Output Spec Template

Template body:

# Brainstorm topic stub: <title>

> This is a brainstorm stub. The `/interview` skill will read it and run the iterative Q&A. Follow the instructions in the "For /interview" section.

## Idea

<one-paragraph problem statement from $ARGUMENTS + clarifier answer>

## Project context (inferred)

- Stack: <e.g. Rust + tokio>, <repo patterns spotted>
- Existing patterns: <bullet list of relevant docs / code paths>
- Constraints surfaced from recall: <if any>

## Subject type(s)

<UI | TUI | API | data model | architecture | CLI | config | state machine | mixed>

## Initial hypotheses

Three candidate approaches. **`/interview` MUST present these via AskUserQuestion in its first round, using the ASCII preview field shown below for each.**

### A: <name>  (recommended)

<one-line rationale>

```
<ASCII preview drawn from the matching library section>
```

### B: <name>

<tradeoff vs A>

```
<ASCII preview>
```

### C: <name>  (optional - only if there's a real third path)

<tradeoff>

```
<ASCII preview>
```

## ASCII preview library

Inlined slices from `{{HOME_TOOL_DIR}}/skills/brainstorm/assets/ascii-library.md` that match this brainstorm's subject type(s). `/interview` uses these in subsequent AskUserQuestion `preview` fields.

<paste the matching subject-type sections here>

## For /interview

**Read this carefully before starting the interview.**

- **First round**: present the three approach hypotheses above via AskUserQuestion. Set `preview` to the ASCII block under each.
- **Subsequent rounds**: drill into architecture, data model, interface, behavior, errors, testing. **Every option-style question MUST use `AskUserQuestion`** with `preview` populated from the library above when comparing concrete shapes.
- **One question per turn** (or 2-4 if naturally batched). Multi-choice preferred.
- **Topics to cover** (skip if N/A): architecture / data model / interface (UI/API/CLI/TUI) / happy path / 2-3 critical edge cases / error handling / testing strategy / out of scope / open questions.
- **Output**: write the spec to `<this-stub-basename>-spec.md` using the "Output Spec Template" section below — **NOT** the default `/interview` corporate template.

### Format preferences (apply to BOTH chat outputs AND spec file)

Per Stevie's CLAUDE.md `<flow_diagrams>` rule. Boundary:

| Content shape                                | Use                                              |
|----------------------------------------------|--------------------------------------------------|
| Flow / sequence / relationships / state      | ASCII box+arrow diagram (`┌─┐ │ └─┘ ─▶ ▼`)        |
| Tabular DATA (rows × columns of facts)       | markdown pipe table                              |
| Discrete items, no ordering                  | bullet list                                      |
| Picks / open questions                       | `- [ ]` checklist                                |
| Prose / narrative paragraphs                 | AVOID — break it into one of the above           |

Rules:
- **Diagram FIRST, table SECOND** when both apply to the same section.
- Diagram width ≤ 80 chars.
- Caveman inside boxes (short technical terms, never sentences).
- Sequence diagrams (vertical lifelines) ONLY for protocol handshakes / back-and-forth.
- Branching trees ONLY for explicit if/else logic.
- No prose-only sections in the spec. Every section must be diagram + table + bullets.

## Output Spec Template

```markdown
# Spec: <title>

**Generated from:** <stub-path>
**Date:** <YYYY-MM-DD>
**Format:** diagram-first, table-second, no prose paragraphs

## Problem

| Question | Answer            |
|----------|-------------------|
| What?    | <one-liner>       |
| Why?     | <motivator>       |
| Who?     | <primary user>    |

## Users + use cases

| Persona     | Goal                | Primary use case          |
|-------------|---------------------|---------------------------|
| <persona 1> | <what they want>    | <core flow they trigger>  |
| <persona 2> | <...>               | <...>                     |

## Approach

| Option | Summary       | Tradeoff           | Picked? |
|--------|---------------|--------------------|---------|
| A      | <name>        | <vs B and C>       |  ✓      |
| B      | <name>        | <vs A>             |         |
| C      | <name>        | <vs A>             |         |

**Why A:** <one line>

## Architecture

<ASCII box+arrow diagram, ≤ 80 chars wide>

| Component | Purpose      | Owns                |
|-----------|--------------|---------------------|
| <name>    | <one-liner>  | <data / behavior>   |

## Data model

<ASCII entity + relationship diagram>

| Entity   | Fields (key only)        | Relationships    |
|----------|--------------------------|------------------|
| <name>   | id, ...                  | 1:N to <other>   |

## Interface

ASCII previews per applicable subject type (UI wireframe | TUI screen | API endpoints | CLI sample | config schema).

| Surface    | Trigger              | Shape                 |
|------------|----------------------|-----------------------|
| <name>     | <user/system event>  | <method / screen / cmd> |

## Behavior

Happy path (ASCII flow):

[start] ──action──▶ [state-1] ──action──▶ [state-2] ──ok──▶ [done]

Edge cases:

| Scenario          | Trigger              | Expected behavior        |
|-------------------|----------------------|--------------------------|
| <case 1>          | <condition>          | <what happens>           |
| <case 2>          | <condition>          | <what happens>           |
| <case 3>          | <condition>          | <what happens>           |

## Errors

| Failure mode    | User-visible surface       | Recovery              |
|-----------------|----------------------------|-----------------------|
| <e.g. 500>      | <toast / log / silent>     | <retry / fallback>    |
| <network drop>  | <...>                      | <...>                 |

## Testing strategy

| Layer       | Scope                              | Coverage gate       |
|-------------|------------------------------------|---------------------|
| Integration | <flows covered>                    | <must-pass>         |
| E2E         | <user-visible journeys>            | <must-pass>         |
| Unit        | <only where logic is non-trivial>  | <if applicable>     |

## Out of scope

- <explicit item 1>
- <explicit item 2>

## Open questions for /plan

- [ ] <question 1>
- [ ] <question 2>
```

After writing the stub, DO NOT answer the questions yourself. Hand off to /interview.

Step 7: Invoke /interview

Filename contract (used in Steps 8-11): /interview writes its output as <input-basename>-spec.md next to the input file. So given <topic>-stub.md as input, the output is <topic>-stub-spec.md. Every path reference in this skill depends on this contract — if /interview's output suffix ever changes, update Steps 8-11.

Invoke:

Skill(skill: "interview", args: ".agents/specs/YYYY-MM-DD-<topic>-stub.md")

/interview will:

• Read the stub
• Detect the embedded ## Output Spec Template section and use it (NOT the default template)
• Detect ## Initial hypotheses, ## ASCII preview library, ## For /interview sections and honor them
• Run AskUserQuestion rounds — starting with the three approach hypotheses, then drilling into design
• Write the spec to .agents/specs/YYYY-MM-DD-<topic>-stub-spec.md

Wait for /interview to complete and return control.

Step 8: Read back the spec

Read .agents/specs/YYYY-MM-DD-<topic>-stub-spec.md. Confirm it exists and is non-trivial.

Step 9: Spec self-review

Fresh-eyes pass with these gates. Fix inline; don't re-loop.

| Gate | What to look for | |--------------|-----------------------------------------------------------------| | Placeholder | TBD, TODO, <...>, empty sections | | Consistency | sections contradicting each other; arch ≠ behavior | | Ambiguity | requirements interpretable two ways - pick one, make explicit | | Scope | still one project, or did it bloat? if bloated, decompose again | | YAGNI | unrequested features creeping in - strip |

Only flag issues that would cause real planning problems. Minor wording, stylistic preferences - leave alone.

Step 10: User-review gate

"Spec written to .agents/specs/YYYY-MM-DD-<topic>-stub-spec.md. Review it. Changes welcome before we finalize + move to /plan."

Wait for explicit approval. If changes requested → fix → re-run self-review → re-ask.

Step 11: Rename + commit

After approval. The stub and stub-spec files were created by Write (untracked by git), so use plain mv / rm, NOT git mv / git rm (which require tracked files):

mv .agents/specs/YYYY-MM-DD-<topic>-stub-spec.md .agents/specs/YYYY-MM-DD-<topic>.md
rm .agents/specs/YYYY-MM-DD-<topic>-stub.md
git add .agents/specs/YYYY-MM-DD-<topic>.md
git commit -m "feat(spec): add <topic> design spec"

One atomic commit; only the final spec lands in history (stub was scaffolding).

Step 12: Handoff to /plan

Invoke /plan (via Skill tool) with the final spec path. Do NOT invoke /implement, framework codegen, or anything else.

ASCII Preview Library

The library lives in a sibling file:

{{HOME_TOOL_DIR}}/skills/brainstorm/assets/ascii-library.md

Read this file before scaffolding the stub (Step 6). Embed the matching subject-type slice(s) inline in the stub's ## ASCII preview library section so /interview has the templates available in-context.

Subjects covered: UI / TUI / API / Data model / Architecture / CLI / Config / State machine.

Key principles

• Brainstorm orchestrates, /interview runs the Q&A - don't duplicate Q&A logic
• The stub is the contract - put everything /interview needs in there (hypotheses, ASCII library slice, output template, instructions)
• Heading exact-match - stub headings (## Initial hypotheses, ## ASCII preview library, ## For /interview, ## Output Spec Template) must EXACTLY match what /interview scans for. No em-dash suffixes, no rewording.
• AskUserQuestion mandatory for any A/B/C decision (per CLAUDE.md <option_presentation>) — applies to both skills
• ASCII preview per option when shapes are being compared
• Multi-choice preferred over open-ended
• YAGNI ruthlessly - strip unrequested features at every gate
• Spec is the deliverable, not code
• Decompose before stub-ing for large projects

Anti-patterns to avoid

• Doing the Q&A inside /brainstorm instead of delegating → defeats the integration
• Writing a thin stub that doesn't give /interview enough → it will ask shallow questions
• Plaintext markdown option tables in stub or interview → AskUserQuestion only
• HTML / browser companions → terminal + ASCII only
• Writing a stub with unresolved <placeholders> → wastes /interview's first round (see HARD-GATE + Step 6)
• Auto-running /plan without user-review gate → wait for explicit approval (HARD-GATE)
• Renaming stub-spec with git mv instead of plain mv → fails on untracked files