brainstorm

``` ██████╗ ██████╗ █████╗ ██╗███╗ ██╗███████╗████████╗ ██████╗ ██████╗ ███╗ ███╗ ██╔══██╗██╔══██╗██╔══██╗██║████╗ ██║██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗████╗ ████║ ██████╔╝██████╔╝███████║██║██╔██╗ ██║███████╗ ██║ ██║ ██║██████╔╝██╔████╔██║ ██╔══██╗██╔══██╗██╔══██║██║██║╚██╗██║╚════██║ ██║ ██║ ██║██╔══██╗██║╚██╔╝██║ ██████╔╝██║ ██║██║ ██║██║██║ ╚████║███████║ ██║ ╚██████╔╝██║ ██║██║ ╚═╝ ██║ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ``` # Brainstorm to an approved spec Most failed work isn't bad code — it's the wrong thing built confidently. This skill closes the gap between what the user said and what they meant, *before* a line is written. ## The method: grill, don't interview - **One question at a time.** A wall of questions gets shallow answers. Ask the single highest-leverage question, get the answer, then ask the next. - **Always propose your own recommended answer** with a one-line why. Make it easy for the user to say "yes" or "no, because…" — don't offload all the thinking onto them. - **Explore the code to answer your own questions** whenever you can, instead of asking. Asking what you could have discovered wastes the user's time. - **Surface trade-offs and disagreements.** If the user's framing has a tension or a simpler alternative exists, say so now. - Walk every branch of the decision tree until there's nothing material left unresolved. ## The HARD GATE Do **not** write implementation code, edit files, or jump to a plan until the user has approved a written spec. This gate is the whole point — it's the cheapest place to be wrong. When you think "this is simple enough to just build," that's exactly when a 2-minute spec saves an hour. Present the spec in **digestible sections** — problem, scope, approach, **risks & assumptions** (a 30-second pre-mortem: "assume this shipped and failed; top 2-3 reasons"), what's explicitly out of scope, and success criteria — and get sign-off section by section, not as one giant block. **"Approved" is mechanical, not inferred.** Approval = the user affirmatively says yes to the section you explicitly presented. Silence, an "ok" aimed at something else, a fresh question, or a topic change is **not** approval — if unsure, ask "Approve this section?" verbatim and wait. Assuming consent from a non-answer is the rationalization this gate exists to forbid. ## Capture decisions as you go (don't batch) - Maintain a **CONTEXT.md glossary** of the project's terms — definitions only, *no implementation details*. When a term gets pinned down, update it immediately. - Record an **ADR** (architecture decision record) only when **all three** hold: the decision is hard to reverse, it would be surprising to a newcomer without context, and it's the result of a real trade-off. Otherwise an ADR is noise. - Durable artifacts contain **no file paths or line numbers** — they rot. Describe behavior, not locations. ## Exit **Write the approved spec to a file** (e.g. `docs/specs/<feature>.md`, or as the header of the plan) so `forge:plan` consumes an artifact, not scrollback — durable facts belong in files, not fragile conversation memory. Then hand off to `forge:plan`, not directly to coding. Brainstorm decides *what* and *why*; plan decides *the steps*.