| name | specpowers-brainstorm |
| description | Use as stage 1 of specpowers-flow — turn a raw idea into an approved direction and a proposal.md draft. Produces problem statement, scope boundary, success criteria, non-goals, risks, and open questions. |
Purpose
This skill owns stage 1 of the specpowers-flow pipeline. It takes an unformed idea and produces a
direction that is concrete enough to generate a change: a named change, a clear problem statement,
agreed-upon scope, testable success criteria, explicit non-goals, known risks, and a list of open
questions that must be resolved before specification work can begin.
The discipline ends with an approved direction and a proposal.md draft written directly into the
change directory. There is no separate brainstorm document — the proposal is the brainstorm
output.
Brainstorm discipline
Work one question at a time. Do not present a complete answer in one shot. Surface uncertainty
rather than burying it in confident-sounding prose. When multiple approaches exist, name them,
weigh them, and record the one chosen and why.
The conversation moves through four phases:
-
Understand the problem. What is broken, missing, or desired? Who is affected? What evidence
shows this is real? Ask one clarifying question at a time and wait for the answer before moving
on. Resist restating the idea as a solution; keep exploring the problem space.
-
Frame the scope. Draw a boundary around what this change will and will not touch. Name the
systems, data, users, and behaviors inside the boundary. Explicitly list what is excluded. A
fuzzy scope is a blocker; do not advance until the boundary is crisp.
-
Explore approaches. Identify at least two realistic implementation directions. For each,
state its key tradeoff, rough reversibility, and any high-risk surface (authentication,
permissions, schema changes, irreversible operations, billing, tenant boundaries). Surface
tradeoffs directly — do not recommend without showing the alternatives. Record the chosen
direction and the rationale.
-
Resolve open questions. List every unanswered question that could invalidate the chosen
direction or block spec generation. For each, state who can answer it and what the impact is if
it is answered differently.
Required outputs
Before the completion gate can be evaluated, the following six elements must be present in
openspec/changes/<change>/proposal.md (see references/openspec-artifact-format.md for the
full proposal shape including required sections):
| Output | What it must contain |
|---|
| Problem statement | One paragraph: current situation, the gap or failure, and measurable impact |
| Scope boundary | What is in scope (systems, behaviors, data); what is explicitly out of scope |
| Success criteria | Numbered, testable conditions — each must be verifiable without interpretation |
| Non-goals | Explicit list of outcomes this change does not pursue, to prevent later scope creep |
| Risks | Each risk identified during approach exploration, with severity and a mitigation or acceptance note |
| Open questions | Every unresolved question with owner and consequence if answered differently |
These outputs are written directly into openspec/changes/<change>/proposal.md as the draft
takes shape during the brainstorm. They are not copied into a separate file afterward. The
proposal draft and the brainstorm output are the same artifact.
If no change directory exists yet, create it at openspec/changes/<change>/ using the chosen
change name before writing the file.
Completion gate
The brainstorm stage is complete when both of the following are true:
-
Direction approved. The human has explicitly accepted the chosen approach and scope. A lack
of objection is not acceptance; ask for it directly.
-
Requirement is specific enough to generate a change. The problem statement, scope, and
success criteria are concrete enough that specpowers-spec can produce design.md, tasks.md,
and a spec delta from them without guessing. If ambiguity remains that would force a spec author
to make unstated assumptions, resolve it here first.
If either condition is not met, continue the brainstorm. Do not advance.
What this stage does NOT do
- It does not generate
design.md, tasks.md, or spec deltas — those belong to specpowers-spec.
- It does not write implementation code or validation commands.
- It does not attempt to resolve open questions by inventing answers; it surfaces them.
Handoff
When the gate is satisfied, hand control back to the orchestrator (specpowers-flow). The
orchestrator will confirm tier selection (informed by the scope and any high-risk surfaces
identified during brainstorm) and route to specpowers-spec for stages 2–3.
Next stage: specpowers-spec — generate OpenSpec artifacts from the approved proposal, then
harden them via validation and adversarial review.
