Brainstorming Into a GitHub Issue

Overview

Reuse the full

superpowers:brainstorming

dialogue, but persist the spec as a GitHub issue instead of a

docs/

file — and persist it incrementally, across sittings. The issue is created early with a

[DRAFT]

title prefix and rewritten after every answer, so you can walk away and resume anytime. On final approval the prefix is stripped and the issue becomes the durable "what/why" spec. This skill ends the moment the issue is finalized; implementation is a separate, later concern.

Core principle: brainstorming's dialogue is medium-agnostic and reused unchanged. Only its persistence (steps 6-9) is overridden — and here that persistence is a resumable draft lifecycle, not a single end-of-session write.

When to Use

You want a spec captured somewhere trackable and linkable, not buried in
```
docs/
```
.
You want to brainstorm over time — start now, answer more questions later — without losing context between sittings.
Building will happen later or by someone/something else — the issue is the handoff.

When NOT to use: you're about to implement immediately in this same session with no need for a durable spec artifact (use

superpowers:brainstorming

directly), or the spec belongs in a versioned design doc.

State Model

Two title states, no new labels:

Title	Meaning
`[DRAFT] feat(scope): summary`	brainstorm in progress (resumable)
`feat(scope): summary`	approved — reads like any normal repo spec issue

Find in-progress drafts with:

gh issue list --search "[DRAFT] in:title"

Entry: Start, Dedupe, or Resume

Determine which mode you're in before asking any questions. Exact

gh

commands are in

issue-lifecycle.md

dot

digraph entry {
    "Issue number given?" [shape=diamond];
    "Load issue, read body + Brainstorm log" [shape=box];
    "Search open issues for a match" [shape=box];
    "Plausible placeholder/draft found?" [shape=diamond];
    "Ask user: adopt #N or start fresh?" [shape=box];
    "Create [DRAFT] issue immediately" [shape=box];
    "Resume the loop from next open question" [shape=doublecircle];

    "Issue number given?" -> "Load issue, read body + Brainstorm log" [label="yes"];
    "Issue number given?" -> "Search open issues for a match" [label="no"];
    "Search open issues for a match" -> "Plausible placeholder/draft found?";
    "Plausible placeholder/draft found?" -> "Ask user: adopt #N or start fresh?" [label="yes"];
    "Plausible placeholder/draft found?" -> "Create [DRAFT] issue immediately" [label="no"];
    "Ask user: adopt #N or start fresh?" -> "Load issue, read body + Brainstorm log" [label="adopt"];
    "Ask user: adopt #N or start fresh?" -> "Create [DRAFT] issue immediately" [label="fresh"];
    "Load issue, read body + Brainstorm log" -> "Resume the loop from next open question";
    "Create [DRAFT] issue immediately" -> "Resume the loop from next open question";
}

Issue number given ("brainstorm gh issue 47") → this is the resume/adopt path. Load it. If it lacks the
```
[DRAFT]
```
prefix or the structured body, add them (fold any existing body text into Summary/Motivation) — see
```
issue-lifecycle.md
```
.
No number → dedupe first, with BOTH searches (you may have already logged a placeholder):
1. ```
gh issue list --state open --search "<keywords>"
```
2. ```
gh issue list --search "[DRAFT] in:title"
```
If a plausible match exists, surface it and ask before adopting. Never silently reuse.
No match → create the
```
[DRAFT]
```
issue immediately, from the raw idea, with a mostly-TBD body. Do this before the dialogue so nothing is ever conversation-only.

The Draft Lifecycle (core loop — all 4 steps)

REQUIRED SUB-SKILL: Run
```
superpowers:brainstorming
```
for the dialogue — steps 1-5 exactly as written: explore context, clarifying questions one at a time, propose 2-3 approaches, present the design in sections, get user approval. Do NOT collapse this into a single self-answered pass; the one-question-at-a-time HIL loop is the point.
Override inside that sub-skill — its persistence only (brainstorming's own steps 6-9 are replaced by this skill):
- Never write a spec file under
```
docs/
```
  (no
```
docs/superpowers/specs/…
```
  ).
- Never commit a spec doc.
- Never invoke
```
writing-plans
```
  — there is no plan step here.
- The spec's only home is the GitHub issue. This override removes brainstorming's ending only — when the dialogue completes, continue with THIS skill's Finalize → Ready below.
Persist after EVERY answer — all three parts, immediately, every round (see
```
issue-lifecycle.md
```
):
1. Fold the answer into the relevant spec section.
2. Check off the answered log item.
3. Set the next
```
[ ]
```
  question.
Not batched, not deferred to the end: a hard interruption after any answer must leave the issue current. Build each update from the issue's current body — never regenerate it from conversation memory, and never drop, shorten, or paraphrase earlier answers.
Repeat until the design is presented and approved.

The body is the living spec; a

## Brainstorm log

section (visible while draft) carries the checkboxed Q&A + the next open question, which IS the resume state.

Finalize → Ready (all 5 steps, in order)

Pre-finalize gate — when the design is approved, confirm each check aloud before editing:

The user explicitly approved the presented design.
The issue body is current through the latest answer (nothing exists only in conversation).
No
```
docs/
```
spec file was written and
```
writing-plans
```
was never invoked.

Then:

Spec self-review on the issue body: scan for placeholders/TBDs, internal contradictions, scope creep, ambiguous requirements. Fix inline.
Strip the
[DRAFT]
prefix from the title.
Collapse
## Brainstorm log
into a
<details>
block at the bottom so the spec reads clean by default while the decision trail stays recoverable.
Show the user the issue URL and ask them to review. If they request changes, edit and re-run the self-review. This is the spec review gate — keep it.
STOP. The issue is the handoff. Do not branch, plan, or implement.

Exact commands for all of the above are in

issue-lifecycle.md

Issue Backend:

gh

This skill deliberately uses GitHub issues (
gh
). Do not route the spec to a non-GitHub tracker and do not hesitate — the whole purpose of this skill is a GitHub-issue spec. (If a caller genuinely wants a different tracker, they want a different skill, not this one.)

Downstream (out of scope — do not do it here)

Implementation happens later. When it does, any implementation plan is optional, scope-gated, and lives in the PR description — never in

docs/

, never in this issue. This skill does not produce or persist a plan.

Common Mistakes

Mistake	Fix
Creating the issue only at the end	Create the `[DRAFT]` issue on start (or adopt one); persist every round
Batching persistence / holding answers in conversation only	Update the issue body after EVERY answer
Silently reusing a found issue	Surface the match and ask before adopting
Skipping the dedupe search when no number is given	Search open issues first — a placeholder may already exist
Stopping when brainstorming's steps 6-9 are overridden	The override replaces those steps with THIS skill's Finalize → Ready — run it
Finalizing without stripping `[DRAFT]`	Ready = prefix stripped + log collapsed to `<details>`
Following brainstorming to a `docs/` file + commit	Divert per the persistence override; the issue is the only artifact
Invoking `writing-plans`	No plan step — stop at the issue
Self-answering all clarifying questions in one pass	Run the real one-question-at-a-time dialogue with the user
Ad-hoc issue structure that differs every run	Use the template in `issue-lifecycle.md`
Hardcoding `--repo owner/name`	Run from the repo; let `gh` infer from the remote
Compressing or summarizing recorded decisions as the body grows	Never — fidelity first; if the body nears GitHub's 65,536-character limit, surface it and ask the user to split the spec into multiple issues

Red Flags — STOP

About to ask questions before the
```
[DRAFT]
```
issue exists (or is adopted)
Answers accumulating in the conversation but not on the issue
About to shorten or summarize recorded spec content (for any reason, including GitHub's 65k body limit) instead of asking the user to split the spec
About to reuse a found issue without asking
Finalizing with the
```
[DRAFT]
```
prefix still in the title
About to write anything under
```
docs/superpowers/specs/
```
About to invoke
```
writing-plans
```

All of these mean: get the draft issue current first, with real HIL approval, before continuing.

brainstorming-to-issue

NPX Install

Tags

SKILL.md Content