# How the Brainstorming Skill Works in Superpowers: A Complete Technical Guide > Discover how the brainstorming skill in Superpowers enforces design before implementation. Learn the six-step checklist and hard-gated state machine for approved feature designs. - Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers) - Tags: deep-dive - Published: 2026-02-16 --- **The brainstorming skill in Superpowers is a mandatory, process-oriented workflow that enforces design-before-implementation by running a six-step checklist through a hard-gated state machine, ensuring every feature starts with an approved design document.** The Superpowers repository (`obra/superpowers`) implements a rigid creative workflow through its **brainstorming skill**, which acts as a mandatory prerequisite for all implementation tasks. This declarative process ensures that no code is written, refactored, or scaffolded until a thorough design review is completed and documented in the repository. ## What Is the Brainstorming Skill? The **brainstorming skill** is a hard-gated, checklist-driven workflow defined in [`skills/brainstorming/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md). Unlike typical CLI commands that execute imperative code, this skill declares a state machine that the Superpowers engine parses and enforces. It serves as the entry point for all creative work, preventing premature implementation through explicit `` constraints that block any writing or scaffolding operations until design approval is granted. ## How the Brainstorming Skill Is Invoked ### The CLI Command Entry Point Users trigger the workflow by executing: ```bash superpowers brainstorm ``` This command maps to [`commands/brainstorm.md`](https://github.com/obra/superpowers/blob/main/commands/brainstorm.md), which contains minimal configuration. The file instructs the engine to invoke `superpowers:brainstorming` and defer all output generation to the skill implementation itself. ### Disabling Direct Model Output The command file sets `disable-model-invocation: true`, preventing the CLI handler from generating autonomous responses. This flag ensures that **only** the scripted dialogue defined in the skill's checklist can produce output, maintaining strict process control and preventing the AI from skipping steps. ## Skill Discovery and Resolution ### Locating the Skill File When the command is parsed, the engine calls `resolveSkillPath` from [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) (lines 99-138). This utility searches for [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) in the following order: 1. Personal skill directory (user overrides) 2. Built-in `skills/brainstorming` directory This resolution strategy allows custom implementations to shadow the default workflow while maintaining fallback integrity to the built-in skill. ### Extracting Metadata The `extractFrontmatter` function (lines 5-15 of [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)) parses the YAML header of [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) to retrieve the skill name and description. This metadata populates help listings and validates the "skill-name: brainstorming" resolution required by the engine to confirm the correct skill is loaded. ## The Hard-Gate Enforcement Mechanism The `` section (lines 14-16 of [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md)) declares a strict precondition: **no implementation skill, code write, or scaffold may be invoked until a design has been presented and approved**. The engine enforces this by rejecting transitions to "write-plan", "frontend-design", or similar nodes until the brainstorming flow reaches the "Invoke writing-plans" state. This creates an immutable barrier between ideation and execution, ensuring architectural decisions are documented before coding begins. ## The Six-Step Checklist Process The skill defines a mandatory six-step checklist (lines 22-31) that structures the creative workflow: 1. **Explore project context** – Analyze existing files, documentation, and recent commits to establish baseline understanding. 2. **Ask clarifying questions** – Engage in one-question-per-message interaction to resolve ambiguities. 3. **Propose 2-3 approaches** – Present alternative solutions with explicit trade-offs and a clear recommendation. 4. **Present design** – Break the proposal into sections, requesting approval after each segment. 5. **Write design doc** – Persist the approved design to `docs/plans/YYYY-MM-DD--design.md`. 6. **Transition to implementation** – Automatically invoke the `writing-plans` skill to begin execution. ## State Machine and Process Flow The workflow is visualized as a DOT graph (lines 35-52) representing a finite state machine. After user approval of the design, the skill writes the design document and hands control to the `writing-plans` skill. This declarative approach ensures that the engine, not the user, manages state transitions according to the predefined graph, preventing skipped steps or premature execution. ## Implementation Guards and Constraints The skill enforces strict interaction patterns through two key constraints embedded in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md): - **One question at a time** (lines 59-64): The dialogue protocol prohibits multi-part questions to maintain clarity and prevent overwhelming the user. - **Multiple-choice preferred** (lines 91-93): When presenting options, the skill must use structured multiple-choice formats rather than open-ended prompts, reducing ambiguity in user responses. These constraints are enforced by the engine's dialogue parser, ensuring consistent user experience across all brainstorming sessions. ## Summary - The **brainstorming skill** is a mandatory, declarative workflow defined in [`skills/brainstorming/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) that gates all creative work in Superpowers. - It is invoked via `superpowers brainstorm`, which delegates to the skill while disabling direct model output through `disable-model-invocation: true`. - The engine uses `resolveSkillPath` and `extractFrontmatter` from [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) to locate and parse the skill definition. - A **hard-gate** prevents any implementation until the six-step checklist is completed and the design is approved. - The process enforces structured dialogue through "one question at a time" and "multiple-choice preferred" constraints. ## Frequently Asked Questions ### What triggers the brainstorming skill in Superpowers? The skill is triggered by executing `superpowers brainstorm` in the CLI. This command maps to [`commands/brainstorm.md`](https://github.com/obra/superpowers/blob/main/commands/brainstorm.md), which instructs the engine to invoke the `superpowers:brainstorming` skill and disables direct model invocation to ensure the skill's scripted workflow controls all output. ### Why does the brainstorming skill use a hard-gate mechanism? The hard-gate, defined in the `` section of [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md), ensures that no implementation work—such as writing code, scaffolding, or invoking planning skills—can occur until a design has been presented and explicitly approved. This prevents premature execution and enforces design-first development practices. ### How does Superpowers locate the brainstorming skill files? The engine calls `resolveSkillPath` from [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) to locate [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md). It first checks the personal skill directory for user overrides, then falls back to the built-in `skills/brainstorming` directory. Once found, `extractFrontmatter` parses the YAML header to retrieve metadata like the skill name and description. ### What constraints does the brainstorming skill place on user interaction? The skill enforces two primary dialogue constraints: the "one question at a time" rule, which prohibits multi-part questions to maintain clarity, and the "multiple-choice preferred" principle, which requires presenting options as structured choices rather than open-ended prompts. These constraints are embedded in the skill definition and enforced by the engine's dialogue parser.