brainstorming

Overview of brainstorming skill

What the brainstorming skill is for

The brainstorming skill is a structured pre-implementation workflow for turning a rough idea into an approved design before any code is written. Its main job is not “generate ideas” in the abstract; it is to reduce rework by forcing scope, assumptions, requirements, and design choices into the open first.

Who should install this brainstorming skill

This brainstorming skill is best for people who regularly jump too quickly from “we should build X” to implementation. It is especially useful for:

• feature planning
• component design
• behavior changes
• internal tool proposals
• brainstorming for Requirements Planning

If you already have a disciplined spec process, this skill can still help as a lightweight front-end to that process.

What makes it different from a normal prompt

The key differentiator is the hard gate in SKILL.md: the agent should not implement, scaffold, or write code until it has presented a design and received approval. That sounds simple, but it materially changes behavior compared with ordinary “help me build this” prompting, where assistants often skip straight to solutions.

What users actually care about before installing

Most users want to know three things fast:

1. Will this slow me down?
2. Will it ask useful questions instead of generic ones?
3. Can it help with visual design discussions?

The answer is: it adds process overhead on purpose, but the overhead is small when the idea is small. The skill explicitly argues that even “simple” work needs a short design pass, because that is where hidden assumptions create expensive mistakes.

How to Use brainstorming skill

brainstorming install and setup

To add the skill from the repository, use:
npx skills add https://github.com/obra/superpowers --skill brainstorming

After install, open these files first:

• skills/brainstorming/SKILL.md
• skills/brainstorming/visual-companion.md
• skills/brainstorming/spec-document-reviewer-prompt.md

If you expect visual exploration, also inspect:

• skills/brainstorming/scripts/start-server.sh
• skills/brainstorming/scripts/frame-template.html

The core workflow the skill expects

The brainstorming usage pattern is opinionated:

1. explore project context
2. optionally offer the visual companion
3. ask clarifying questions one at a time
4. synthesize the design
5. get explicit approval
6. only then move into planning or implementation

If your agent skips from idea to code, it is not really following this skill.

What input to provide for better brainstorming usage

The skill works best when you give more than a feature title. Good starting input usually includes:

• the problem to solve
• who the user is
• current system or repo context
• constraints
• what “done” looks like
• known non-goals

A weak input:

Add notifications.

A stronger input:

Add in-app notifications for failed background imports. Users are operations staff, not end customers. We already have email alerts, but they are too slow for live triage. Keep scope to the admin dashboard only. Do not add mobile push or user preference management in v1.

That second version gives the brainstorming skill enough structure to ask sharper follow-up questions.

How to turn a rough idea into a strong first prompt

A practical prompt template for brainstorming:

Use the brainstorming skill for Requirements Planning.
Context: [project/repo/product]
Problem: [what is happening now]
Target user: [who is affected]
Constraints: [timeline, stack, compliance, UX, compatibility]
Non-goals: [what not to solve]
Please ask clarifying questions one at a time, then present a proposed design for approval before any implementation.

This aligns with the skill’s intended flow and reduces the chance of generic questioning.

How clarifying questions should work

One subtle but important behavior: the skill expects questions one at a time, not as a giant discovery questionnaire. That matters because answers often reshape the next question. If your agent dumps 15 questions at once, you lose the interactive refinement this brainstorming guide is designed to create.

When to use the visual companion

The repository includes a browser-based visual companion. Use it when the user would understand options better by seeing them:

• wireframes
• layout comparisons
• UI flows
• architecture diagrams
• state or relationship visuals

Do not use it just because the topic mentions UI. A conceptual question like “should this be a wizard or a modal?” can stay in text. A question like “which of these two wizard layouts is clearer?” is a strong fit for the visual path.

How the visual companion is actually served

The visual helper is not just documentation; there are scripts for running a local session:

• scripts/start-server.sh
• scripts/stop-server.sh
• scripts/server.cjs
• scripts/helper.js

start-server.sh starts a local server on a random high port and can store session files either under /tmp or inside a project directory such as .superpowers/brainstorm/. This is useful if you want mockups to persist across sessions.

Practical environment notes before you rely on visuals

The visual workflow assumes a browser-accessible environment. If you are in a remote container, VM, or SSH workflow, pay attention to:

• --host
• --url-host
• session directory persistence

For local-only usage, the defaults are straightforward. For shared or remote environments, plan the networking details before you build the workflow around browser feedback.

Best file-reading path for quick adoption

If you want the shortest path to real usage quality, read in this order:

1. SKILL.md for the behavioral contract
2. visual-companion.md for when browser support helps
3. spec-document-reviewer-prompt.md for what “good enough to implement” looks like
4. scripts/start-server.sh if you need the visual path

This gives you the decision logic first, then the optional tooling.

What good output from brainstorming should look like

A successful brainstorming session should end with a design that is concrete enough to review, including:

• goal and user
• scope boundaries
• key decisions
• open risks or assumptions
• enough specificity to plan implementation

If the output is only a loose idea list, the session stopped too early.

How to use brainstorming for Requirements Planning

For brainstorming for Requirements Planning, use the skill as the pre-spec step:

1. clarify the problem and constraints
2. draft the design or requirements shape
3. get approval
4. write the spec
5. run the spec reviewer prompt template if needed

This is one of the strongest uses of the skill because it catches scope drift and ambiguity before planning gets locked in.

brainstorming skill FAQ

Is brainstorming skill only for big projects?

No. The skill explicitly rejects the idea that “small” work can skip design. The expected design may be short for a tiny change, but the design step still matters. The value is often highest on supposedly simple changes where assumptions go untested.

Is this better than ordinary brainstorming prompts?

Usually, yes, if your real goal is execution-ready clarity rather than idea volume. A normal brainstorming prompt may generate many options. This brainstorming skill is better when you need convergent thinking: understand context, narrow choices, and produce an approved design.

Is the brainstorming skill beginner-friendly?

Yes, especially for solo builders who do not yet have a planning habit. The structure compensates for a common beginner mistake: implementing the first plausible idea without clarifying requirements or tradeoffs first.

When is brainstorming a poor fit?

Skip or shorten it when:

• the task is purely mechanical and already fully specified
• you are not making a design or behavior decision
• the user already approved a detailed spec and just needs execution

Even then, verify the hard gate does not conflict with your workflow. This skill is intentionally strict.

Does this skill generate code?

No, and that is deliberate. The brainstorming skill is supposed to stop before implementation until approval is given. If you want code generation, use this skill first, then hand off to a planning or implementation skill after approval.

Do I need the visual companion to get value?

No. The browser path is optional. Text-only brainstorming usage still gives most of the value for requirements, scope, and technical tradeoff discussions. The visual tools matter most when the decision itself is visual.

How to Improve brainstorming skill

Give the brainstorming skill richer project context

The fastest way to improve results is to anchor the discussion in reality:

• relevant files or folders
• existing behavior
• recent changes
• known technical constraints
• affected users

The skill itself tells the agent to explore project context first. Help it by naming where that context lives.

State constraints and non-goals early

Many weak brainstorming outputs come from under-specified boundaries. Tell the skill what it must preserve or avoid:

• backward compatibility
• performance limits
• compliance or security requirements
• timeline or staffing limits
• features explicitly out of scope

This produces narrower, more decision-useful designs.

Ask for a design, not just ideas

If you want implementation-ready output, say so. Ask the brainstorming skill to end with:

• a proposed design
• assumptions
• unresolved questions
• explicit approval checkpoint

That steers the session away from endless ideation and toward a usable artifact.

Use stronger prompts for visual brainstorming

For visual work, do not say only “show mockups.” Specify what the visual needs to compare:

Show two dashboard layout options for failed import alerts: one optimized for fast triage, one optimized for detail review. Keep the existing navigation shell. Highlight which option better supports keyboard-heavy operators.

That kind of prompt helps the visual companion create decision-oriented output instead of decorative screens.

Watch for the main failure mode: premature solutioning

The biggest failure mode is jumping to implementation details before the problem is actually understood. If that happens, redirect the session:

Pause implementation thinking. What assumptions are we making about the user workflow, edge cases, and scope boundaries?

That keeps the brainstorming guide aligned with its core purpose.

Improve the first output through one review pass

After the initial design, ask for a focused revision rather than restarting:

• what is ambiguous?
• what is over-engineered?
• what would break implementation planning?
• what is missing for approval?

The repository’s spec-document-reviewer-prompt.md is useful here because it calibrates review around real planning blockers, not cosmetic edits.

Keep the brainstorming artifact small but decision-complete

A common mistake is inflating the design with unnecessary detail. Better brainstorming is not longer brainstorming. For simple work, a few tight paragraphs covering purpose, scope, constraints, approach, and approval can be enough. The standard is not document length; it is whether the next step can proceed with less guesswork.

Pair brainstorming with a spec review step

If you adopt this skill seriously, combine it with a follow-up review of the produced spec or design. The included reviewer template checks for:

• placeholders
• contradictions
• ambiguous requirements
• over-broad scope
• unrequested complexity

That makes the brainstorming skill more useful in a real delivery workflow, not just in chat.