brainstorm

brainstorm

standalonewriteshands-on

Use this when: a fuzzy idea needs shaping into a spec before any code

Problem it solves — A vague idea turned straight into code becomes the wrong code, confidently. Brainstorm holds it in thinking-mode across two diamonds — goal first, then problems, then solutions — widening with blind helpers so you don't anchor on your first idea, behind a gate that won't build until you approve the spec.

Used in workflows: Idea → shipped · Grow the harness

Brainstorm

A vague idea turned straight into code becomes the wrong code, confidently. This skill keeps the idea in thinking mode — two diamonds, problems then solutions — until building it is mechanical, and opens the build gate only when you say so.

Three layers, each measured against the one above — Goal → Problems → Solutions. Scratchpad names the goal first (solution-free); problems are named relative to the goal; solutions are scored on how well they serve it. The goal is the lens every later stage is held against, and the top of the rubric.

Governing principle — recommendations, not decisions. Claude and every subagent recommend; you make every final call. Nothing self-advances — every step waits on your input (a lens pick, a review depth, an export, a token). The deliberate friction is the point: it stops both the agent skipping and you rubber-stamping.

Standing principle — never downgrade the process on a hunch of "simple". The full process runs every time: the EFFORT prompt before every diverge, the blind ideate fan-out, the HTML+JSON review surface at every handoff, the REVIEW red-team after every diverge and converge. Never decide a step is simple enough to skip — "it's simple" is exactly when the skip bites, and you can't see the unknown-unknowns by definition. A green spike proves the slice is buildable, not the problem solved — probe harder, don't stop.

Tone. Plain-language first; technical detail in its own **🔧 Technical** box. Positive framing — say what to do. Applies to stage prose, banners, and every brief.

Run it from the files, not from memory — re-read every step

The bespoke mechanics live in the step files, not in generic "double diamond" knowledge — and over a long brainstorm the launch-time procedure gets buried and compressed out of context. So it is re-injected just-in-time:

• On launch: Read playbook.md + decks.md, then post a short workflow brief to the maintainer — the steps, where they'll be asked to act (pick lenses; choose a review depth; review + export on an HTML page; type the tokens) — so they know what to expect and can catch a skipped step.
• On entering any step — first time or re-entry — your first action is to Read stages/<step>.md, then post its phase contract + the steps you'll run + quote its PHASE-TOKEN, before doing the work. Re-read every entry; the token is your proof you read the file this turn, not from recall. Reconstructing a step from memory is the exact failure this guards against (code-quality.md: confidence is not evidence).

Step files: stages/scratchpad · effort · explore · viability · curate · review · build. Each owns its unskippable checklist; decks.md holds the lens decks, rubric.md the yardstick, templates/ the review surfaces, playbook.md the cross-cutting mechanics (build-spikes, enforcement, Reopen).

The flow

The two diamonds break into fine steps. stage: (frontmatter) tracks the coarse diamond position for resume + the gate; you Read the fine step file as you hit each. Every step waits on you; tokens land at the diamond boundaries.

Each diamond stage carries both names — the canonical one (which the gate + frontmatter use) and the plain one (what's actually happening): Discover = Problem Exploration · Define = Problem Curation · Develop = Solution Exploration · Deliver = Solution Curation. (Exploration = the divergent widen; Curation = the convergent narrow — the harness-wide terms the gate + glossary still use under the hood.)

SCRATCHPAD · Goal     scratchpad → name the goal · review(goal, soundness)
  ══ NEXT ══ (goal gate: goal named + reviewed)
🔵 DISCOVER · Problem Exploration   effort(problems) · explore · review(pool, completeness)
  ══ NEXT ══
🟣 DEFINE · Problem Curation        curate(problems → review-problems.html, export) · review(set, soundness)
  ══ NEXT ══
🟢 DEVELOP · Solution Exploration   effort(solutions) · explore · review(pool, completeness) · viability
  ══ NEXT ══
🟠 DELIVER · Solution Curation      curate(pick → review-decisions.html, export) · review(pick, soundness) · coverage
  ══ BUILD ══ (coverage proven)

Banners (emit verbatim, first line, on entering each diamond):

━━ SCRATCHPAD · Goal ━━  dump anything; exit by naming the goal this work serves
━━ DISCOVER · Problem Exploration ━━  name every problem; ranking and scope come later
━━ DEFINE · Problem Curation ━━  pick the problems this work solves; park the rest
━━ DEVELOP · Solution Exploration ━━  generate many solutions; ranking waits
━━ DELIVER · Solution Curation ━━  triage viability, pick, gate to BUILD

The record is the state

One folder per brainstorm, docs/brainstorms/<date>-<slug>/: brainstorm.md (journey doc + frontmatter + Scratchpad/Discover/Define/Develop/Deliver/Graveyard/ Parked/Method-log sections), the review pages + their exported review-<role>-state.json, spikes/. The frontmatter is the single source of truth for where you are — read by any resume and the gate hook. Stamp session: with $CLAUDE_CODE_SESSION_ID so the gate scopes to this session. To bin one, set stage: trashed (ask first).

---
brainstorm: <slug>
session: <$CLAUDE_CODE_SESSION_ID>   # owning session — scopes the gate hook to this agent
stage: scratchpad        # scratchpad | discover | define | develop | deliver | done | trashed
goal:                    # the single solution-free primary goal; full frame in the Goal section
gates:                   # each flips true only on the maintainer's UPPERCASE token
  scratchpad_to_discover: false
  discover_to_define: false
  define_to_develop: false
  develop_to_deliver: false
  deliver_to_build: false
updated: 2026-06-09T16:35Z
---

The fine-step marks (lenses_<phase>, external_<phase>, viability_<id>, review_<x>_depth, the review-*-verdict.json / review-*-state.json files) record which step actually happened — the deterministic layer the gate hook reads. See playbook.md → Enforcement.

Coverage gate — mandatory before any plan

Before Deliver hands off: build the problem → solution map; every in-scope problem must have at least one adopted solution. An uncovered gap (its only solution rejected or left 'maybe') triggers a targeted re-diverge (mini-diamond) or an explicit maintainer won't-fix — never shipped silently. (Detail in stages/build.md.)

Hand-off

On BUILD: run find-learnings first; then route by size — many decisions → to-issues, a single change → the matching build-* — carrying the spec doc + the exported review-<role>-state.json files. Parked problems become Idea-typed GitHub issues, sub-issue-linked from their parent. Promote to an ADR only for a durable, architecturally significant decision — surface-then-confirm first.

Where it sits

• Not grill-me — that hardens a plan you already have; brainstorm shapes a fuzzy idea you haven't pinned down.
• Not vet — that judges an idea's worth + placement; brainstorm shapes an idea you've decided to pursue (pair: brainstorm → unsure it's worth it? → vet).
• Not check-reasoning — brainstorm invokes it (the soundness reviews) rather than being its target.
• Not find-harness-improvements — that ideates over the whole harness; brainstorm shapes one named idea end to end.