vasu-devs/forge/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.