automagik-dev/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:

# 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:

   git add .genie/brainstorms/<slug>/DESIGN.md .genie/brainstorms/<slug>/DRAFT.md
   

   Per .gitignore, only DESIGN.md and DRAFT.md are trackable under .genie/brainstorms/*/ — no force-add needed. Other brainstorm artifacts (session notes, transcripts, scratchpads) remain workspace-local.
4. Update .genie/brainstorm.md — move item to Poured with wish link.
5. Auto-invoke /review (plan review) on the DESIGN.md.

Output Options

| Complexity | Output | |-----------|--------| | Standard | Write DESIGN.md, auto-invoke /review (plan review) | | Small but non-trivial | Write design, ask whether to implement directly | | Trivial | Add one-liner to jar (Raw section), no file needed |

Handoff

After /review returns SHIP on the design:

Design reviewed and validated (WRS {score}/100). Proceeding to /wish.

Note any cross-repo or cross-agent dependencies — these become depends-on/blocks fields in the wish.

Stuck Decisions

If the Decisions dimension stays ░ (unfilled) after 2+ exchanges, suggest:

Decisions seem stuck. Consider running /council to get specialist perspectives on the tradeoffs.

Design Template

Use this structure when writing DESIGN.md at crystallize:

# Design: <Title>

| Field | Value |
|-------|-------|
| **Slug** | `<slug>` |
| **Date** | YYYY-MM-DD |
| **WRS** | 100/100 |

## Problem
One-sentence problem statement.

## Scope
### IN
- Concrete deliverable 1
- Concrete deliverable 2

### OUT
- Explicit exclusion 1

## Approach
Chosen approach with rationale. Reference alternatives considered.

## Decisions
| Decision | Rationale |
|----------|-----------|
| Choice 1 | Why this over alternatives |

## Risks & Assumptions
| Risk | Severity | Mitigation |
|------|----------|------------|
| Risk 1 | Low/Medium/High | How to handle |

## Success Criteria
- [ ] Testable criterion 1
- [ ] Testable criterion 2

Task Lifecycle Integration (v4)

On crystallize, create a draft task in PG so the brainstorm is tracked in genie task list:

On crystallize (WRS = 100)

# Create draft task (starts at draft stage by default)
genie task create "<brainstorm title>" --type software

# Link to the design draft
genie task comment #<seq> "Draft: .genie/brainstorms/<slug>/DRAFT.md"

| Event | Command | |-------|---------| | Crystallize | genie task create "<brainstorm title>" --type software | | Link draft | genie task comment #<seq> "Draft: .genie/brainstorms/<slug>/DRAFT.md" |

Graceful degradation: If PG is unavailable or genie task commands fail, warn but do not block the crystallize flow. The DESIGN.md and brainstorm jar are the source of truth — PG tasks are an optional tracking enhancement.

Rules

• One question per message. Never batch questions.
• YAGNI and simplicity first.
• Always propose alternatives before recommending.
• Never assume requirements without confirmation.
• No implementation during brainstorm.
• Persist early and often — do not wait until the end.
• Always git add both DESIGN.md and DRAFT.md on crystallize — the wishes-lint linter will fail CI on any wish that links to an uncommitted brainstorm.

Turn close (required)

Every session MUST end by writing a terminal outcome to the turn-session contract. This is how the orchestrator reconciles executor state — skipping it leaves the row open and blocks auto-resume.

• genie done — work completed, acceptance criteria met
• genie blocked --reason "<why>" — stuck, needs human input or an unblocking signal
• genie failed --reason "<why>" — aborted, irrecoverable error, or cannot proceed

Rules:

• Call exactly one close verb as the last action of the session.
• blocked / failed require --reason.
• genie done inside an agent session (GENIE_AGENT_NAME set) closes the current executor; it does not require a wish ref.