brainstorm

# /brainstorm — Explore Before Planning

Collaborate on fuzzy ideas until they are concrete enough for `/wish`.

## When to Use
- User has an idea but unclear scope or approach
- Requirements are ambiguous and need interactive refinement
- User explicitly invokes `/brainstorm`

## Context Injection

This skill is multi-agent aware and operates on the shared worktree:
- All brainstorm artifacts live in `.genie/` within the shared worktree (not the repo root)
- When invoked via dispatch, acknowledges injected context (file path + extracted section) and uses it as seed
- Multiple agents can read brainstorm state concurrently; writes are coordinated by the orchestrator

## Flow
1. **Read context:** scan current code, docs, conventions. Check `.genie/brainstorm.md` in the shared worktree for an existing entry matching this slug/topic — use as seed if found. If context was injected from dispatch, use it directly.
2. **Init persistence:** create `.genie/brainstorms/<slug>/DRAFT.md` immediately in the shared worktree. Create `.genie/brainstorm.md` if missing (see Jar).
3. **Scope-size check:** if the request touches multiple independent subsystems, flag for decomposition before refining details (see Scope-Size Detection).
4. **Clarify intent:** one question at a time, prefer multiple-choice.
5. **Show WRS bar** after every exchange (see WRS).
6. **Persist draft** when WRS changes OR every 2 minutes — whichever comes first.
7. **Propose approaches:** 2-3 options with trade-offs. Apply Design-for-Isolation principles. Recommend one.
8. **Crystallize** when WRS = 100: write `DESIGN.md`, spec self-review, update jar, hand off.

## Scope-Size Detection

Before refining any details, assess whether the request is a single cohesive project or multiple independent ones. Multi-subsystem requests waste brainstorm cycles because refinement assumptions for subsystem A may not hold for subsystem B.

**Signs the request needs decomposition:**
- Touches 3+ unrelated directories or modules
- Requires changes to both infrastructure and application layers
- Combines UI + API + data model changes with no shared interface
- Different parts could ship independently without blocking each other
- Different parts would naturally be assigned to different engineers

**When detected:**
1. Stop refining details immediately.
2. Tell the user: "This looks like it spans multiple independent subsystems. Refining them together risks a wish that's too broad to execute cleanly."
3. Help decompose into sub-projects, each getting its own brainstorm → wish → work cycle.
4. For each sub-project, identify: purpose, rough scope, and dependencies on other sub-projects.
5. Start a fresh brainstorm for the first sub-project (or let the user pick).

## Design-for-Isolation

When proposing approaches and writing the Approach section of DESIGN.md, apply these principles:

- **Single purpose per unit** — each module, file, or component should do one thing well. If you can't describe its purpose in one sentence, it's doing too much.
- **Well-defined interfaces** — units communicate through explicit contracts (function signatures, event schemas, API endpoints), not shared mutable state or implicit conventions.
- **Independent testability** — each unit can be understood and tested without loading the full system. If testing requires spinning up 5 other services, the boundaries are wrong.
- **File size as complexity signal** — when a file grows large, that's a signal it's doing too much. Propose splits before the file becomes unmanageable, not after.
- **Explicit dependencies** — every dependency between units should be visible in the interface, not hidden in implementation details.

These principles apply to the design itself, not just the code that implements it. A design that produces isolated, testable units is easier to execute, review, and maintain.

## WRS — Wish Readiness Score

Five dimensions, 20 points each. Show the bar after every exchange.

| Dimension | Filled when… |
|-----------|-------------|
| **Problem** | One-sentence problem statement is clear |
| **Scope** | IN and OUT boundaries defined |
| **Decisions** | Key technical/design choices made with rationale |
| **Risks** | Assumptions, constraints, failure modes identified |
| **Criteria** | At least one testable acceptance criterion exists |

### Display Format

```
WRS: ██████░░░░ 60/100
 Problem ✅ | Scope ✅ | Decisions ✅ | Risks ░ | Criteria ░
```

- ✅ = filled (20 pts) — enough info to write that section of a wish
- ░ = unfilled (0 pts) — still needs discussion
- **< 100:** keep refining
- **= 100:** auto-crystallize

## Jar

Brainstorm index at `.genie/brainstorm.md`. Tracks all topics across sessions.

**On start:** create if missing. Prefer `templates/brainstorm.md`; otherwise auto-create with sections:

```markdown
# Brainstorm Jar
## Raw
## Simmering
## Ready
## Poured
```

| Event | Action |
|-------|--------|
| Start | Look up slug/topic (fuzzy match) — use as seed context |
| WRS change | Update entry to reflect current section (Raw/Simmering/Ready) |
| Crystallize | Move entry to Poured, link resulting wish |

## Crystallize

Triggered automatically when WRS = 100.

1. Write `.genie/brainstorms/<slug>/DESIGN.md` from `DRAFT.md` using the Design Template below.
2. **Spec self-review** — before invoking /review, run this 4-point checklist on the DESIGN.md:
   1. **Placeholder scan** — any TBD, TODO, or incomplete sections? Fill them or mark as explicit OUT-of-scope.
   2. **Internal consistency** — do sections contradict each other? (e.g., scope says X is OUT but success criteria tests X)
   3. **Scope check** — focused enough for a single wish? If it spans multiple independent subsystems, split before proceeding.
   4. **Ambiguity check** — could any requirement be interpreted two different ways? Tighten the language.
   Fix issues inline in the DESIGN.md, then continue.
3. **Stage both files for commit:**
   ```bash
   git add .genie/brainstorms/<slug>/DESIGN.md