---
name: superpower-brainstorming
description: Internal fork of superpowers:brainstorming with approval gates stripped. Use when a parent skill needs structured Q&A + design + spec doc, without user "approve design / review spec" wait points.
user-invocable: false
---

# Brainstorming Ideas Into Designs (Internal, Gate-Free)

Help turn ideas into fully formed designs and specs through natural collaborative dialogue. This is an **internal fork** of `superpowers:brainstorming`: `<HARD-GATE>`, "approve design", "review spec", and Visual Companion have been removed so the flow can run without user-facing confirmation breaks. QA (AskUserQuestion) is still used freely for genuine ambiguity.

**Caller contract:** the parent skill passes in (or this skill derives) a spec output path. Once the spec file is written and self-reviewed, control returns to the caller. This skill does NOT chain to any next skill itself.

**No human-fill markers in output.** The spec you write is CC's internal reasoning artifact, not a user-review doc. Do NOT emit `【人工填写：...】` style placeholders — that convention belongs to A-phase docs (`docs/01~10`, `CLAUDE.md`, `.env.local`), not B-phase specs/plans. When a concrete value is needed:

1. **Look up first** — check `.env.local`, `docs/07-环境配置.md`, `CLAUDE.md`, existing code. If the value is already resolved somewhere, cite that source in the spec (e.g., "JWT_SECRET 从 `.env.local` 读取，`application.yml` 用 `${JWT_SECRET}` 注入")
2. **Ask via `AskUserQuestion` second** — if no source exists, ask the user directly; record their answer in the spec
3. **Never leave a 【人工填写：】 placeholder** — if step 1 + 2 somehow can't resolve it, the spec must name the exact blocker (not a generic human-fill marker), and Q&A keeps going until it's resolved

## Checklist

Complete in order:

1. **Explore project context** — check files, docs, recent commits relevant to the topic
2. **Ask clarifying questions** — one at a time, only for genuine ambiguity; understand purpose / constraints / success criteria
3. **Pick an approach** — if multiple viable approaches exist, briefly weigh trade-offs and pick the best; surface the choice only if the user's answer to a prior Q&A did not already decide it
4. **Write design doc** — save to the path provided by the caller (default `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` if none)
5. **Spec self-review** — inline check for placeholders, contradictions, ambiguity, scope; fix inline
6. **Return control to caller** — no further chaining

## Process Flow

```dot
digraph brainstorming {
    "Explore project context" [shape=box];
    "Ask clarifying questions\n(one at a time)" [shape=box];
    "Pick approach\n(weigh trade-offs only if needed)" [shape=box];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "Return to caller" [shape=doublecircle];

    "Explore project context" -> "Ask clarifying questions\n(one at a time)";
    "Ask clarifying questions\n(one at a time)" -> "Pick approach\n(weigh trade-offs only if needed)";
    "Pick approach\n(weigh trade-offs only if needed)" -> "Write design doc";
    "Write design doc" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "Return to caller";
}
```

## The Process

**Understanding the idea:**

- Check current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), surface this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
- If the project is too large for a single spec, help decompose: what are the independent pieces, how do they relate, what order to build? Then brainstorm the first sub-project through the normal design flow.
- For appropriately-scoped projects, ask questions one at a time
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message
- Focus on understanding: purpose, constraints, success criteria

**Approach selection:**

- If there is a single obvious approach driven by the Q&A answers, just use it
- If trade-offs remain, briefly state 2-3 approaches + your recommendation inline in the spec (not as a confirmation gate)

**Design for isolation and clarity:**

- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
- For each unit you should be able to answer: what does it do, how do you use it, what does it depend on
- Smaller, well-bounded units are easier to reason about and test; large files are a signal of doing too much

**Working in existing codebases:**

- Explore the current structure before proposing changes. Follow existing patterns.
- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design — the way a good developer improves code they're working in.
- Don't propose unrelated refactoring. Stay focused on what serves the current goal.

## After Q&A

**Write the design doc:**

- Write the validated design (spec) to the caller-provided path (default `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`)
- Cover: goal, inputs/outputs, rules, constraints, schema/API refs, acceptance criteria — or match the template the caller expects

**Spec self-review (no user wait):**

1. **Placeholder scan:** any "TBD", "TODO", "【人工填写：...】", incomplete sections, vague requirements? Fix them — either resolve via file lookup, raise a `AskUserQuestion`, or rewrite the passage to be concrete.
2. **Internal consistency:** do any sections contradict? Does architecture match feature descriptions?
3. **Scope check:** focused enough for a single implementation plan, or needs decomposition?
4. **Ambiguity check:** could any requirement be interpreted two ways? Pick one, make it explicit.

Fix inline. No re-review — just fix and move on.

**Terminal state:**

Return control to the caller. Do not invoke writing-plans, frontend-design, or any other skill from here.

## Key Principles

- **One question at a time** — don't overwhelm
- **Multiple choice preferred** — easier to answer
- **QA for ambiguity only** — don't fabricate confirmation questions
- **YAGNI ruthlessly** — remove unnecessary features from designs
- **Incremental understanding** — clarify when something doesn't make sense
- **No approval gates** — writing the spec is the commit; any disagreement surfaces as a concrete Q&A item