Brainstorming gets a design doc approved before Claude Code builds anything
One question at a time, two or three approaches to choose from, and a gate where installing a dependency already counts as building
Claude Code is good at building, and it builds what it believes I asked for. That belief is usually thinner than it feels, and the gap is where I lose afternoons. Brainstorming is the skill I install to close it. It stops at the idea, asks until it understands what I actually want, and does not start building until I have approved a design.
It is adapted from Jesse Vincent’s superpowers collection, it sits in the development category of the catalog, and it is at version 2.0.0.
What Brainstorming does to a session
It does not wait for the word “brainstorm”. Its description tells Claude to use it before creating features, adding functionality, modifying behavior or planning anything new, in software or out of it.
Once it fires, the order is fixed:
- It reads first. In an existing project it goes through the code the change would touch, and it is told never to ask what the project already answers.
- One question per message. One sentence, no stacked questions, no menu of example answers attached. The red flags table in the skill is blunt about why a menu is worse than a question: options steer, so get them describing it first.
- It plays the design back in chunks of 200 to 300 words as it goes, marking which parts are mine and which are its own proposals.
- It sends the approaches in a message of their own: two or three real options with trade-offs, the weak ones dropped, its recommendation first with a reason.
- It writes the design doc and asks for approval.
There is an escape hatch, and it is the reason a description that greedy is tolerable. If I never asked for brainstorming, it adds one line offering to just dive in instead. If I take it, the skill is done for that turn.
The gate, and what actually enforces it
The approval gate is the part worth knowing, because it is wider than “do not write code”. The skill counts all of this as building:
- product code
- scaffolding
- installing dependencies
- creating projects
- invoking an implementation skill
That last one closes the usual workaround, where the agent does not write the code itself, it just calls the skill that does. Reading, exploring, and a mockup or a spike I agreed to stay allowed, and keeping what a spike produced is treated as a new request that comes back through the gate.
Here is the caveat the skill file does not give you. This gate is prompt text. Claude Code’s permissions documentation is explicit that rules are enforced by Claude Code and not by the model, and that instructions in a prompt or in CLAUDE.md shape what Claude tries to do rather than what it is allowed to do. Nothing in the runtime refuses a Write call because a design doc has not been approved. Two things follow:
- Skill content loads once and is not re-read, so in a long session the gate is a memory rather than a check.
- If you want it actually enforced, that is a PreToolUse hook or a deny rule, not a skill.
I run it as a thinking aid, not as a control, and on those terms it earns the install.
Install it, then decide how loudly it fires
npx claude-code-templates@latest --skill development/brainstormingThat writes to .claude/skills/brainstorming/: the SKILL.md plus a references/builder-check.md that only gets read when it is needed. Only the frontmatter sits in context at session start, the body loads when the skill is invoked, and the reference file later still.
Get Daniel Avila’s stories in your inbox
Join Medium for free to get updates from this writer.
Then read that description again, because the description is the trigger. “You MUST use this before any creative or build work”, with “skip it only for fully specified one-line tasks”, means the skill wants to fire on almost everything. On a repo where I am making small, already decided changes, that is noise.
Two switches:
{
"skillOverrides": {
"brainstorming": "user-invocable-only"
}
}user-invocable-only keeps it out of automatic invocation and leaves /brainstorming working when I want it. The /skills menu writes this into .claude/settings.local.json. The other values are on, name-only and off.
The skill-side equivalent is disable-model-invocation: true in the frontmatter, which also stops it being preloaded into a subagent.
Where the design doc lands
After I pick an approach it sizes the work, and I can override the size. A small change gets a short design in the chat, a line or two per point. A project gets a written document, and in a repo it goes to docs/plans/YYYY-MM-DD-<topic>-design.md unless the project already has its own convention. Both include an Approaches section: what was considered, what it trades off, which one I picked and why.
For projects there is one more step I had not seen inside a skill before. Before the doc is handed over it runs a builder check: a fresh reader, a subagent or itself reading as a stranger, gets the document with the conversation stripped out and is asked for nothing except the questions a builder would still have to guess at, ranked. What comes back is sorted into already answered, minor (settle it and mark it as its own call), and mine. The last pile comes back in a single message. One round, then the doc is finished.
One caveat there too: the SKILL.md hands off to a writing-plans skill "if installed". There is no documented mechanism for one skill to depend on another, so that sentence is prompt text like the rest. If you do not have that skill, nothing fails and nothing warns you, you just get a numbered plan instead.
Why this sits above plan mode
Plan mode is a permission mode. It holds back edits while a plan is written for work that has already been decided. Brainstorming runs upstream of that, on deciding what the work is.
Claude Code did ship something closer to this once. I wrote about Ultraplan when it quietly disappeared, and my read then was that the idea was fine and the execution environment was the problem.
Whether writing things down first actually pays is not settled either. The CMU and Google study on spec driven development I went through covered 266 repositories and 21 practitioners. Most specs carried implementation details, developers reported more reliable agents along with more planning and review overhead, and the researchers could not separate the benefit of the method from models simply getting better.
What I keep from that is the part that does not depend on the document: the value is being forced to say what I want out loud, early. A skill that asks one question at a time is a cheap way to be forced.
Where the Skills live
- Brainstorming on aitmpl.com
- Systematic Debugging, the sibling skill for after it is built
- The rest of the skills catalog
Everything else is at aitmpl.com.
You can follow me on my social media:
- Twitter (English): https://x.com/dani_avila7
- LinkedIn (Spanish): https://www.linkedin.com/in/daniel-avila-arias/
- Youtube (Spanish): https://www.youtube.com/@daniiielsan
- Instagram (Spanish): https://www.instagram.com/danielsan_avila/
👏 Clap if you enjoyed this article
