Brainstorming Skill

We read the file at commit b36e082 of obra/superpowers. The catalog copy is byte-identical to GitHub, so every quote below reads the same in both places.

brainstorming at a glance

1. It fires before you ask for it, because the description is written as a trigger on all creative work and the bundle's entry-point skill re-fires it before plan mode.
2. There are three paths and the label only ratchets up, announced out loud so you can override it, and never downgraded mid-task.
3. "Too simple to need approval" is the failure it targets, with a red-flag table of the exact rationalizations that skip the gate.
4. The divergence it asks for is small, capped at two or three approaches on the architectural path alone, delivered recommendation first.
5. It writes a spec to disk and commits it, then hands off to the one sibling skill that is allowed to write next.
6. The spec review went inline, and the prompt file it used to dispatch still ships, in two skills.
7. The visual companion is a real server, a Node process writing into your repo, and every screen it serves phones home by default.

1. It fires before you ask for it

The description field is what an agent reads when it decides whether to load a skill at all. This one is written as an order rather than a summary.

description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."

Source: SKILL.md, frontmatter

"Modifying behavior" is the phrase doing the work. Most skills load when you name them, and "help me brainstorm" is the obvious case. This description also reaches "add a flag" and "change what that button does", neither of which anybody would call brainstorming. A second trigger comes from the bundle's entry-point skill, using-superpowers, whose full text the plugin's hooks/session-start script reads and injects into every session. That one arrives only if you installed superpowers as a plugin.

Before entering plan mode: if you haven't already brainstormed, invoke the brainstorming skill first.

Source: using-superpowers/SKILL.md, "The Rule"

What the skill does once loaded is refuse to build.

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have told your human partner what you intend and they have approved it. This applies to EVERY task on EVERY path below — the ceremony scales with the task; the approval gate never does.

Source: SKILL.md, "HARD-GATE"

That is the whole product. The rest of the file is machinery for deciding how much ceremony precedes the yes. The price is that an agent holding this skill cannot answer a build request by building, and the skill has no size threshold below which it stops caring. SKILL.md runs to 15 KB, which is what a trigger this broad pulls into context.

2. Three paths, and the label only ratchets up

The agent has to state which path it picked before it asks its first question, and the file even supplies the sentence it should say, so that you can override the call at the point it is made. A spike is a feasibility question whose output is an answer and whose code is labelled throwaway. A bounded task is a small change to a flow that already exists in the repo. Architectural covers new projects and anything that moves an interface other code depends on. The tie-break rule is where the file gets opinionated.

When in doubt between two paths, take the heavier one. The ratchet is one-way: hidden complexity discovered mid-task upgrades the path — stop, say so, and step up. Nothing downgrades mid-task.

Source: SKILL.md, "Three Paths"

A one-way ratchet with a doubt tie-break biases the whole thing upward, and the definition of "bounded" is written to keep it that way.

| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |

Source: SKILL.md, "Red Flags"

So a greenfield project can never be bounded, however small it looks. npm init plus one file is architectural under this rule, which means questions one at a time, two or three approaches, a sectioned design and a committed spec before the first line exists.

3. "Too simple to need approval" is the failure it targets

The most common objection to a gate like this gets its own heading in the file, ahead of the checklist most readers would skip to.

Every path ends with your human partner approving your intent before implementation. A todo list, a single-function utility, a config change — the design may be two sentences in chat, but you MUST present it and get approval. "Simple" tasks are where unexamined assumptions [...]

Source: SKILL.md, "Anti-Pattern"

Then a seven-row table of thoughts and their rebuttals, written in the agent's own voice. One row catches the specific move an agent makes when it has both the design and the ability to start.

| "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |

Source: SKILL.md, "Red Flags"

Writing the rationalization down before the agent produces it is the same technique the grill-me dive covers from the questioning side. The cost lands on you rather than the agent: the gate converts every small request into at least one extra round trip, and if you are away from the terminal the work stops there.

4. How much divergence does it actually ask for?

Less than the name suggests, and the file says so before it says anything else. SKILL.md is titled "Brainstorming Ideas Into Designs", and its one-line summary is "Help turn ideas into fully formed designs and specs through natural collaborative dialogue." The README repeats the framing twice, as "Socratic design refinement" in the skill list and as "Refines rough ideas through questions, explores alternatives, presents design in sections for validation" in the workflow walkthrough. Convergence is the advertised product. What is worth knowing is how narrow it gets.

The rule for questions sets a slow pace on purpose.

• Only one question per message - if a topic needs more exploration, break it into multiple questions

Source: SKILL.md, "Understanding the idea"

One question per message means a design conversation with six open questions costs six turns before any option is on the table. Two bullets above that rule, the file spends its scope check: if a request describes several independent subsystems, the agent is told to flag that immediately rather than refine details, then help you decompose the work into sub-projects that each get their own spec, plan and implementation cycle. That instruction is scoping rather than ideation, and it pulls in the same direction as everything else in the section.

When options do arrive, the budget is fixed and the framing is settled in advance.

• Propose 2-3 different approaches with trade-offs [...]
• Lead with your recommended option and explain why
• YAGNI ruthlessly - remove unnecessary features from every approach and design

Source: SKILL.md, "Exploring approaches"

Cap the options, put your answer first, delete features from what remains. The risk in that ordering is anchoring, because an alternative presented after a recommendation tends to be read as a formality. Two later subsections lean the same way. "Design for isolation and clarity" asks the agent to break the system into units that each have one purpose and a defined interface, and to read a file that has grown large as a signal it does too much. "Working in existing codebases" tells it to follow the patterns already there and to fold targeted fixes into the design when bad code is in the way, while staying off unrelated refactoring.

The two or three approaches are also architectural-path depth, which the file marks itself: everything from "Exploring approaches" onward serves that path, and bounded work is context plus a few questions plus a short in-chat design. A spike presents the question and what the agent will try in two or three sentences. A bounded task presents one short design in chat. On both of those paths the effective option count is one.

5. What it writes to disk, and who writes next

Spike and bounded work produce no design document. The architectural path produces one, at a location the file hard-codes.

1. Write design doc — save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commit

Source: SKILL.md, "Checklist"

The step ends in a commit, so the design enters your history rather than your chat. The repo shows what that looks like after a while: at this sha obra/superpowers carries nineteen documents under docs/superpowers/specs/, seventeen of them ending in -design.md, alongside fifteen under docs/superpowers/plans/.

The architectural path then terminates on exactly one successor, and the file names the skills it is refusing to call.

Terminal states are path-bound. Architectural: the ONLY skill you invoke after brainstorming is writing-plans — never frontend-design, mcp-builder, or any other implementation skill. Bounded: after approval, implementation proceeds directly through the normal development workflow; no plan document. Spike: the terminal state is a reported recommendation.

Source: SKILL.md, "Process Flow"

writing-plans writes a second document to docs/superpowers/plans/, and stamps a header on it that names the next skill in the chain.

> For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Source: writing-plans/SKILL.md, "Plan Document Header"

So an architectural yes commits you to a spec, then a plan, then subagent-driven-development or executing-plans, with an approval gate at each seam, and none of it produces code.

That chain is also where installing brainstorming by itself leaves a loose end: the terminal state of the heaviest path invokes a skill you would not have. That gap is ours. obra's README documents one install per harness and every one of them takes the whole plugin: /plugin install superpowers@claude-plugins-official for Claude Code, agy plugin install for Antigravity, devin plugins install for Devin. No per-skill install path appears in it. The single-skill command printed at the bottom of this page is a Skillselion affordance, and it is what makes the loose end reachable at all.

6. The spec review went inline, and the prompt file it dispatched still ships

After the spec is committed the agent checks its own work against four items: placeholders, internal contradictions, scope, and requirements that could be read two ways. The closing instruction is unusually relaxed for a file this strict.

Fix any issues inline. No need to re-review — just fix and move on.

Source: SKILL.md, "Spec Self-Review"

That looseness was bought with a measurement. The repo's release notes record why the earlier version, which dispatched a fresh subagent to review the spec, was cut.

The subagent review loop (dispatching a fresh agent to review plans/specs) doubled execution time (~25 min overhead) without measurably improving plan quality. Regression testing across 5 versions with 5 trials each showed identical quality scores regardless of whether the review loop ran. [...] - Self-review catches 3-5 real bugs per run in ~30s instead of ~25 min, with comparable defect rates to the subagent approach

Source: RELEASE-NOTES.md, v5.0.6

The deletion left the template behind. skills/brainstorming/spec-document-reviewer-prompt.md still ships at 1.7 KB, still opens with "Use this template when dispatching a spec document reviewer subagent", and no skill file in the repo at this sha references it. Its surviving mentions are two release notes, the plan that created it and that plan's design doc. The identical leftover sits next door: skills/writing-plans/plan-document-reviewer-prompt.md, 1.7 KB, same opening sentence with "plan" swapped in, equally unreferenced. So this is repo housekeeping rather than anything specific to brainstorming, and obra does do the housekeeping elsewhere. The same release notes announce that spec-reviewer-prompt.md and code-quality-reviewer-prompt.md "are gone", folded into one task-reviewer-prompt.md that subagent-driven-development still points at by name. The two document reviewers missed that sweep.

Once the self-review is done the file adds another approval gate on top of it: the agent asks you to read the committed spec, and writing-plans is only reachable after you say yes to what is on disk.

7. The visual companion is a real server

The last section of SKILL.md offers a browser tab for questions that are genuinely visual. It is the one part of the skill that starts a process on your machine. How the agent is allowed to ask you about it is spelled out to the level of which message it goes in.

This offer MUST be its own message. Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with --open so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it.

Source: SKILL.md, "Visual Companion"

The offer text the file supplies calls the feature "still new" and "token-intensive" in the act of pitching it. Accepting runs scripts/start-server.sh, which launches a 25 KB Node server from the skill folder, serves key-gated HTML screens to localhost and records your clicks as JSON lines the agent reads on its next turn. What it does to your repo is documented in the bundled guide, not in SKILL.md.

Note: Pass the project root as --project-dir so mockups persist in .superpowers/brainstorm/ and survive server restarts. Without it, files go to /tmp and get cleaned up. Remind the user to add .superpowers/ to .gitignore if it's not already there.

Source: visual-companion.md, "Starting a Session"

The .gitignore reminder is there because the mockups land inside your working tree, so the untracked directory is the default outcome rather than an edge case. The server auto-exits after four hours idle, and stop-server.sh ends it sooner.

The server does reach past localhost in one place. Every screen it renders carries a branding block, and that block pulls an image off a remote host.

const SUPERPOWERS_BRAND_IMAGE_URL = 'https://primeradiant.com/brand/superpowers-visual-brainstorming-logo.png';

Source: scripts/server.cjs, module constants

The <img> tag built from it appends ?v= and the installed superpowers version, so opening a mockup tells primeradiant.com that a session is running and which release it is running. Three environment variables turn it off, read once at startup: SUPERPOWERS_DISABLE_TELEMETRY, DISABLE_TELEMETRY, and Claude Code's own CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Set any of them and the logo is dropped. obra discloses all of this himself under a README heading called "Visual companion telemetry", which states what the request carries, what it does not, and how to disable it. The disclosure is honest and easy to find. It just lives in the README, while the file that starts the server is the one an agent actually loads.

Tools it drives: file writes and a git commit for the spec at docs/superpowers/specs/, task-list creation (one task per checklist item on the chosen path), the Skill tool for writing-plans at the architectural terminal state, and, only if you accept the companion, scripts/start-server.sh and scripts/stop-server.sh around a Node HTTP and WebSocket server plus reads of $STATE_DIR/events. It names no test runner and no language, so it sits on top of whatever your repo already uses.

Behavior change, before and after:

The fine print worth knowing:

• A new project is never bounded. The red-flag table rules that familiarity with the kind of app does not shrink the path, so greenfield work takes the full architectural process.
• The spec location is a default that your own preferences override, but the commit is not presented as optional.
• Install brainstorming alone and the architectural path ends by invoking writing-plans, which you will not have. obra ships superpowers as a whole plugin and his README documents no per-skill install, so that loose end belongs to the single-skill route, which is ours.
• spec-document-reviewer-prompt.md here and plan-document-reviewer-prompt.md in writing-plans both still ship at 1.7 KB, and nothing in either skill dispatches them any more.
• The companion writes into .superpowers/ inside your repo when you pass --project-dir, and the guide tells the agent to remind you to ignore it. That guide is another 13 KB, read only if you accept the offer.
• Accepting the companion also loads a logo from primeradiant.com on every screen, with your superpowers version in the query string. SUPERPOWERS_DISABLE_TELEMETRY, DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC switches it off, and obra spells the whole thing out in the README.
• Everything here terminates on a human yes, so unattended runs stop at the first gate.

Should you install brainstorming?

Install it if your complaint is agents that build the wrong thing quickly. The gate plus the red-flag table attack the specific moment where an agent has enough of a design to start and starts, and the spike path gives you a way to ask a cheap question without triggering the heavy process. The bounded checklist hands implementation to the normal workflow with "(TDD applies)" in parentheses, which points at test-driven-development in the same bundle; using-superpowers names systematic-debugging as the other process skill that fires this way, on bug reports instead of build requests.

Skip it if you run agents unattended, because every path ends on a human approving something and the file offers no way to pre-authorize. Skip it too if a skill committing documents into your repo on a fixed path is not something you want. If the name made you expect wide idea generation, the file's own title answers that before you install anything: it reads "Brainstorming Ideas Into Designs". Even on the architectural path the divergence caps at three options with the agent's recommendation first, and on a spike or a bounded task you get one.

npx skills add https://github.com/obra/superpowers --skill brainstorming