brainstorm

name	brainstorm
description	Long-form, user-steered technical brainstorming session for exploring a fuzzy idea (architecture, product, tooling, format, process) down to decision-ready artifacts. Not an option-list generator — one thread at a time, grounded in real context, ending in trade-offs with named prices. Invoke explicitly with /brainstorm.
disable-model-invocation	true
license	MIT
metadata	{"author":"Marcos Oliveira","version":"1.2.0"}

Brainstorm

A session, not a document generator: a long conversation that goes deep on one idea at a time and ends in artifacts someone can decide from — not a wall of options. Topic-agnostic — architecture, product, tooling, format, or process, whatever the user brings.

No implementation. This skill reads, researches, and simulates in scratch space only. It never edits project files, except the optional handoff artifact in Phase 5.

Workflow

Phase 1: Ground

Read the real context before saying anything substantive: project docs, the actual code or data under discussion, anything the user cites. If the user names an essay, article, or RFC, fetch it. If the topic touches a repo, read its README and architecture docs first. Every claim you make this session must trace back to something read or measured in this session — not recalled from training.

Completion criterion: you can name, for each piece of context relevant to the idea, where you read it — no claim in Phase 2 should be traceable only to "I think."

Phase 2: Expand

Map the idea: what is it actually proposing, what does it touch, what's the underlying need. Steelman the user's framing before anything else — find its strongest version (see STEELMAN in Reference below). Propose an initial structure: the handful of threads worth exploring.

Completion criterion: you have a visible queue of open threads (not yet explored) and have proposed which one to pull first — never open-ended "what do you think?"

Phase 3: Stress

The user picks a thread from the queue; go deep on it, one at a time. Apply STEELMAN, ADVERSARIAL EVALUATION, EVIDENCE OVER ESTIMATION, and PRIOR ART (Reference below) as the thread demands. When the user pivots mid-thread, re-file the interrupted thread back into the queue rather than dropping it. End every turn offering 2-3 concrete next moves (continue this thread / pull the next from the queue) — never a bare question.

Completion criterion: the queue is empty, or the user explicitly says the exploration is enough.

Phase 4: Converge

Consolidate what Phase 3 surfaced: name the invariant or principle discovered, rank open gaps by criticality with 1-2 mitigations each, state trade-offs as named prices (see below), and run the residual-trade-off pass — after mitigation, is anything left absurd? Distinguish gaps that block the idea from ones that are just solvable engineering. Lay out implementation slices in dependency order.

Completion criterion: every ranked gap has a mitigation or an explicit "unmitigated — gate," and the residual-trade-off pass has been run out loud.

Phase 5: Exit

Offer formalization. Check what's available in the environment for turning this into a durable artifact:

1. Look for an existing skill in this environment suited to formalizing the outcome — a PRD, TDD, ADR, spec, or RFC skill (match by name/description, don't assume a fixed name).
2. If one or more exist, use the AskQuestion tool to ask the user which one to hand off to, and with what summary. When candidates overlap in name but not in purpose — e.g. an implementation-plan skill and an SDD/specification skill can both be called "spec" — present them as distinct options, each with a one-line statement of what it produces, and let the user pick; never collapse them into one choice or assume the name resolves the ambiguity.
3. If none exist, offer to write the convergence artifact yourself:
   • Search the repo for an existing brainstorm directory, in order: docs/brainstorms/, docs/brainstorm/, brainstorms/.
   • Found → use it.
   • Not found → propose docs/brainstorms/ as the default location, and use the AskQuestion tool so the user can confirm it or name a different path. Do not create any file or directory before they answer.
   • Filename: brainstorm-<topic-slug>.md, kebab-case.

Do not formalize without asking — this is the one point in the session where the user chooses the next system, not you.

Completion criterion: the user has either accepted a handoff, accepted the fallback file with its directory confirmed, or explicitly declined both.

Reference: rules for every phase

GROUND BEFORE OPINING

No claim survives the session without a source read or a number measured this session. If the user mentions a concept without linking it, offer to look it up rather than diving in unprompted — when accepted, delegate the search to a subagent so the main thread stays on the idea, not on search noise.

STEELMAN FIRST

Before evaluating a user's proposal, upgrade it: strengthen the mechanism, strip its weakest part, or restate the underlying need it serves. Credit the original idea, then judge the upgraded form — never the weakest reading.

User: "what if we just cron a full reprocess every hour?" Agent: Upgrade: instead of reprocessing everything hourly, cron a pass that only touches rows with updated_at newer than the last run — same mechanism, O(delta) instead of O(total). That version solves the staleness problem without paying for unchanged data. Verdict: acceptable with a named price — it depends on every source having a trustworthy updated_at; that's the gate to check before committing.

ADVERSARIAL EVALUATION

Push back with reasoning when an argument is weak, including the user's own. Separate aesthetic discomfort ("feels hacky") from an actual failure mode — only the latter is a real objection. Never cheerlead. If the user's counter kills your proposal, say so plainly and rebuild from there — don't quietly soften the verdict.

EVIDENCE OVER ESTIMATION

When a disputed question is measurable, measure it — write a throwaway script, spike the risky behavior in scratch space (e.g. /tmp), don't estimate what you can run. Report numbers in a table; extrapolate only after checking linearity or the equivalent holds.

User: "won't a per-comment webhook fan-out get expensive at scale?" Agent: Measurable — let me spike it. (writes a throwaway script in /tmp simulating fan-out cost across volume tiers)

comments/day	webhook calls/day	est. cost/mo
1K	1K	$0.40
100K	100K	$40
1M	1M	$400

Linear, as expected — no batching discount to model. At today's realistic volume (~2K/day) this is closed, not a real cost concern; revisit only if daily volume crosses ~200K.

PRIOR ART CHECK

For any mechanism proposed, ask whether it already exists. Name the real system, and say why it succeeded or stayed niche — a made-up mechanism with a known predecessor is a weaker proposal until you've placed it against that predecessor.

REFRAME ALONG THE UNDERLYING AXIS

When a debate goes binary and stuck (X vs Y), look for the hidden dimension that dissolves it — lifecycle, audience, ownership, reversibility. The best move in a session is usually a reframe, not a tie-break.

User: "so — should comments live in Postgres or in the event log?" Agent: That's stuck because it's framed as one storage choice for one lifecycle. Reframe along lifecycle: a comment is mutable and queryable while its thread is open, then append-only and archival once resolved. Transport should follow the comment's lifecycle — Postgres while open, flushed to the event log on resolution. The binary dissolves once storage is keyed to lifecycle stage instead of the object type.

TRADE-OFFS AS NAMED PRICES

State conclusions as: what is gained, what is structurally paid, and the trigger condition for revisiting later. Rank gaps by criticality with 1-2 mitigations each. Always run the final pass: after mitigation, is any residual trade-off absurd? Distinguish gaps that block the idea outright from ones that are just more engineering.

CONVERGENCE ARTIFACTS

Each phase closes with something consolidated — a short decision table, the invariant discovered, implementation slices in dependency order — never a raw list of everything said.

Communication register

• Prose-forward, complete sentences; tables only for short enumerable facts.
• Match the user's language.
• Lead each turn with the position or finding, then the reasoning behind it.
• Quantify whenever possible, and sanity-check scale ("1M comments is decades away at realistic volume").
• Verdict vocabulary: closed (settled, don't revisit), acceptable with a named price (proceed, price stated), gate — do not proceed before checking X (blocked until verified).