# Brainstorm

> Turn a vague idea into an approved, written spec before any code is written. Use before building a feature, adding functionality, or changing behavior — whenever the work is more than a trivial mechanical edit and the requirements aren't already pinned down.

- Skill: `vasu-devs/brainstorm` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vasu-devs/brainstorm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vasu-devs/brainstorm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vasu-devs (https://skillmd.com/u/vasu-devs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vasu-devs/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*.