# Brainstorm > Explore ambiguous or early-stage ideas interactively — tracks wish-readiness and crystallizes into a design for wish. - Skill: `automagik-dev/brainstorm` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add automagik-dev/brainstorm` - Raw SKILL.md: https://api.skillmd.com/api/skills/automagik-dev/brainstorm/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: automagik-dev (https://skillmd.com/u/automagik-dev) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/automagik-dev/brainstorm --- # brainstorm — Explore Before Planning **Runtime syntax:** invoke the plugin copy through the active runtime's owner-qualified skill selector; use a bare selector only when intentionally selecting a user-tier copy (a separately installed personal copy; Genie no longer seeds this tier). Cross-skill prose below uses bare names as portable semantic routes; the orchestrator resolves the selector for the active runtime. 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` All artifacts live in `.genie/` within the shared worktree. When spawned as a native subagent, the dispatcher curates seed context (file path + extracted section) into your prompt — use it directly; do not re-read what was already provided. ## Flow 1. **Read context:** scan relevant code, docs, conventions. Check the canonical `.genie/INDEX.md` for an existing entry matching this slug/topic — seed from it if found. If a legacy flat brainstorm jar (the pre-`INDEX.md` single-file index some repos still carry under `.genie/`) exists, migrate it first (see Index). 2. **Init persistence:** create `.genie/brainstorms//DRAFT.md` immediately; create `.genie/INDEX.md` if missing (see Index). 3. **Scope-size check:** if the request spans multiple independent subsystems, decompose before refining (see Scope Size). 4. **Refine:** fill WRS dimensions. Ask only what an unfilled dimension needs — when the request or context already settles a dimension, mark it filled and move on; never re-litigate decisions the user already made. Prefer concrete options over open questions. 5. **Show the WRS bar** after every exchange; persist DRAFT.md whenever WRS changes. 6. **Pass the Simplicity Gate:** establish the simplest complete approach before considering more machinery. Reject speculative complexity or defer it behind a measurable trigger (see Simplicity Gate). 7. **Propose approaches:** 2-3 options with trade-offs, applying Design for Isolation. Recommend one and proceed when the choice follows from the request. 8. **Crystallize** when WRS = 100 (see Crystallize). ## WRS — Wish Readiness Score Five dimensions, 20 points each: | Dimension | Filled when… | |-----------|-------------| | **Problem** | One-sentence problem statement is clear | | **Scope** | IN and OUT boundaries defined | | **Decisions** | Key technical/design choices made with rationale and the Simplicity Gate passes | | **Risks** | Assumptions, constraints, failure modes identified | | **Criteria** | At least one testable acceptance criterion exists | ``` WRS: ██████░░░░ 60/100 Problem ✅ | Scope ✅ | Decisions ✅ | Risks ░ | Criteria ░ ``` ✅ = enough info to write that section of a wish; ░ = still needs discussion. Below 100: keep refining. At 100: auto-crystallize. If **Decisions** won't fill, convene domain experts (see Stuck Decisions). ## Stuck Decisions If **Decisions** stays unfilled after 2+ exchanges, convene **domain experts**: dispatch 2-3 lens subagents in parallel (native delegation surface), each reading a distinct deliberation card from `references/lenses/` relative to the directory containing this loaded `SKILL.md`. When the tradeoff is technical, also read the matching sibling lane skill (`..//SKILL.md`, resolved from this skill directory) when present. Present their perspectives to the user, then keep refining. Escalate to the full `council` workflow when the decision deserves a durable deliberation record. ## Scope Size Multi-subsystem requests waste refinement — assumptions for subsystem A rarely hold for B. Signs: 3+ unrelated modules, infrastructure + application layers together, UI + API + data model with no shared interface, parts that could ship or be staffed independently. When detected: stop refining, tell the user the request spans independent subsystems, decompose into sub-projects (purpose, rough scope, dependencies for each), and start a fresh brainstorm for the first one. ## Design for Isolation Apply to proposed approaches and the DESIGN.md Approach section: - Single purpose per unit — describable in one sentence. - Explicit interfaces and dependencies — contracts, not shared mutable state or hidden coupling. - Independent testability — each unit understandable without loading the whole system. - File size is a complexity signal — propose splits before a unit becomes unmanageable. ## Simplicity Gate Before recommending an approach or declaring **Decisions** filled: 1. State the simplest complete design that satisfies the current user stories. 2. For every added cache, delta, shard, queue, retry state machine, abstraction, or configuration option, name the present requirement or measurement that pays for it. 3. Count the new durable states, recovery paths, and cross-component invariants each option introduces; treat them as product cost, not implementation detail. 4. Prefer bounding current data, separating history behind pagination, recomputing, replacement, and opinionated defaults before synchronization or configurability. 5. Put plausible future machinery under a measurable adoption trigger instead of building it now. “This may scale later” is not evidence. If the more complex approach lacks present evidence, recommend the simpler one. Do not split the difference by shipping dormant machinery: unused branches still impose protocol, test, security, and maintenance cost. ## Index The single brainstorm/planning index is `.genie/INDEX.md`; auto-create it if missing with sections: ```markdown # Plans Index ## Raw ## Simmering ## Ready ## Poured ``` Legacy migration is idempotent: if a repo still carries the pre-`INDEX.md` flat brainstorm jar under `.genie/`, merge each unique entry into the matching section of `.genie/INDEX.md`, verify every legacy entry is present, then remove the legacy file and stage that deletion if it was tracked. Never update or retain both indexes after a successful merge. (The genie repo itself has already completed this migration — its jar is retired; `.genie/INDEX.md` is the sole tracker here.) | Event | Action | |-------|--------| | Start | Fuzzy-match slug/topic — use as seed context | | WRS change | Move entry to the matching section (Raw/Simmering/Ready) | | Design review SHIP | Keep the entry in Ready and invoke `wish` | | Wish plan review SHIP | Move entry to Poured and link the existing approved wish | ## Crystallize At WRS = 100: 1. Write `.genie/brainstorms//DESIGN.md` from DRAFT.md using `references/design-template.md` (in this skill dir) — fill every placeholder. 2. **Spec self-review** — fix inline before handing off: no TBD/TODO leftovers (fill or mark explicit OUT), no contradictions between sections, scope fits a single wish (split if not), no requirement readable two different ways, and the Simplicity Case justifies every mechanism beyond the simplest complete design. 3. Stage the design, draft, and canonical index: ```bash git add .genie/brainstorms//DESIGN.md .genie/brainstorms//DRAFT.md .genie/INDEX.md ``` If migration removed a tracked legacy flat jar, stage that deletion too. The genie repo's wish linter fails any wish whose design link doesn't resolve to a real file — uncommitted brainstorms are missing in CI and sibling worktrees, so never skip the stage. 4. Update `.genie/INDEX.md` — keep the entry under Ready and link the staged DESIGN.md. Do not move it to Poured before a WISH.md exists and its plan review is persisted as `APPROVED`. 5. Create a board pointer; if this fails (no `.genie/genie.db` yet, CLI unavailable), warn and continue — DESIGN.md and `.genie/INDEX.md` in git are the source of truth: ```bash genie task create --title "" ``` 6. Auto-invoke `review` (design review) on the DESIGN.md. The invoking orchestrator receives the verdict, reviewer-returned reviewed-content SHA-256, reviewer agent/thread identifier, and review timestamp; the reviewer remains read-only. 7. **Persist the evidence before handoff.** Resolve `references/design-review-evidence.mjs` from this loaded skill directory. The invoking orchestrator passes the reviewer-returned digest unchanged through `--reviewed-sha256` with the returned verdict, reviewer identifier, and review timestamp, then runs `verify` and stages DESIGN.md again. The stamp command compares that digest to the current reviewable DESIGN.md before writing and rejects an edit made after review. The SHA-256 subject is the exact UTF-8 DESIGN.md with the bounded evidence block removed, so changing any reviewed design content invalidates the evidence and requires a fresh review. Only a verified `SHIP` block permits `wish`; FIX-FIRST/BLOCKED evidence remains auditable but does not advance. ```bash node "/references/design-review-evidence.mjs" stamp ".genie/brainstorms//DESIGN.md" --verdict SHIP --reviewed-sha256 "" --reviewer "" --reviewed-at "" node "/references/design-review-evidence.mjs" verify ".genie/brainstorms//DESIGN.md" git add ".genie/brainstorms//DESIGN.md" ``` ## Output Options | Complexity | Output | |-----------|--------| | Standard | Write DESIGN.md, auto-invoke `review` (design review), then route through `wish` and plan review | | Small but non-trivial | Write the compact design, run design review, then route through `wish` and plan review before any implementation | | Trivial | One-liner in `.genie/INDEX.md` (Raw), no design file | ## Handoff After `review` returns SHIP and the digest-bound evidence verifies on the design: ``` Design reviewed and validated (WRS {score}/100). Proceeding to wish. ``` Invoke `wish` to create and review `.genie/wishes//WISH.md`. Only after the invoking orchestrator has persisted plan SHIP as WISH status `APPROVED` may it move the `.genie/INDEX.md` entry to Poured and link that existing wish. FIX-FIRST or BLOCKED leaves the brainstorm in Ready with the current design/wish link. Never reuse design-review evidence after editing DESIGN.md. `verify` must pass immediately before `wish` consumes the design. Note cross-repo or cross-agent dependencies — they become `depends-on`/`blocks` fields in the wish. ## Rules - KISS and YAGNI are gates, not tie-breakers; speculative machinery blocks crystallization. - No implementation during brainstorm. - Persist early and often — never wait until the end. - Never present an unconfirmed assumption as a settled decision — confirm it or list it under Risks. ## Session close (required) When spawned as a native subagent, your final message IS the completion signal — the dispatcher is notified when you finish; do not poll or emit a separate contract call. End with exactly one terminal outcome as the last word: - **done** — WRS hit 100, DESIGN.md written and staged, design review SHIP evidence persisted and verified, then `wish` handed off. Report the DESIGN.md path. - **blocked** — needs human input or an unblocking signal. State exactly what. - **failed** — aborted or irrecoverable. State why. `blocked` / `failed` must include a one-line reason.