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/<slug>/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:

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 (../<lane>/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:

# 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.)

Crystallize

At WRS = 100:

1. Write .genie/brainstorms/<slug>/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:

   git add .genie/brainstorms/<slug>/DESIGN.md .genie/brainstorms/<slug>/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:

   genie task create --title "<brainstorm 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.

   node "<brainstorm-skill-dir>/references/design-review-evidence.mjs" stamp ".genie/brainstorms/<slug>/DESIGN.md" --verdict SHIP --reviewed-sha256 "<reviewer-returned-sha256>" --reviewer "<agent-or-thread-id>" --reviewed-at "<ISO-8601-UTC>"
   node "<brainstorm-skill-dir>/references/design-review-evidence.mjs" verify ".genie/brainstorms/<slug>/DESIGN.md"
   git add ".genie/brainstorms/<slug>/DESIGN.md"
   

Output Options

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/<slug>/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.