| name | apd-brainstorm |
| description | Use BEFORE writing the APD spec-card.md whenever the task is vague, broad, ambiguous, or has multiple reasonable approaches. Asks ONE question at a time, presents 2-3 options when there are real choices, converges on a design the user explicitly approves. Triggers on "improve X", "what should we", "thinking about", "options", "not sure", "maybe", "vague", "broad", "redesign", any spec-card.md with unclear scope or fewer than 3 R-criteria. For the pipeline gate contract (plan format, rationale format, BLOCKs) load /apd-pipeline-guide — that one is mandatory on every task; this one is for unclear scope. |
| effort | max |
| allowed-tools | Read Glob Grep |
APD Brainstorm
The Iron Law
NO SPEC WITHOUT SHARED UNDERSTANDING FIRST
If you cannot explain the design in one sentence — you are not ready for a spec.
When to use / When to skip
Use when:
- The task is vague, broad, or "improve X" style
- The user gave a destination but no path ("we need user search")
- Multiple reasonable interpretations exist
- You catch yourself making implementation choices the user hasn't seen
Skip when:
- The task is fully specified (file paths, function names, R-criteria) or the
user has already approved a design informally — a genuine 1:1 mirror of a
just-completed task, a single-line bug fix, a hotfix with pre-aligned design
- You are mid-pipeline (spec is locked; raise concerns to user, don't re-brainstorm)
Skipping this skill does NOT skip the pipeline contract: /apd-pipeline-guide
is mandatory on every task regardless, and the spec gate enforces its marker.
This skill answers "WHAT are we building?"; the guide answers "HOW does the
pipeline run?". Only the first question is ever optional.
Process
digraph brainstorm {
"Receive vague task" -> "Read project context";
"Read project context" -> "Ask ONE question";
"Ask ONE question" -> "User answers";
"User answers" -> "Enough clarity?" [shape=diamond];
"Enough clarity?" -> "Ask ONE question" [label="no"];
"Enough clarity?" -> "Present 2-3 approaches";
"Present 2-3 approaches" -> "User picks";
"User picks" -> "Present design summary";
"Present design summary" -> "User approves?" [shape=diamond];
"User approves?" -> "Revise" [label="no"];
"Revise" -> "Present design summary";
"User approves?" -> "Load /apd-pipeline-guide, then spec" [label="yes"];
}
1. Read Context
- CLAUDE.md — stack, architecture
- Recent session-log — what was done before
- Existing code related to the idea
2. Ask One Question at a Time
Do NOT dump a list of questions. Ask one, wait, ask next.
Good: What problem does this solve for the user?
Bad:
1. What problem does this solve?
2. Who is the target user?
3. What's the priority?
...
3. Explore Trade-offs
When there are choices, present 2-3 options concisely:
Two approaches:
A) Server-rendered — simpler, faster initial load, no JS complexity
B) AJAX — smoother UX, no page reload, more JS code
Which fits better?
4. Converge on Design
When enough is clear:
Goal: [one sentence]
Scope: [what's included]
Out of scope: [what's not]
Approach: [technical approach]
Affected files: [list]
Regression surface:
- RS1: [neighbouring behaviour this reaches into and must not break] — **Cover:** [existing <Suite> | new <TestName> | none: <reason>]
(self-contained? then the single line 'none — <reason>'. The gate parses the
`- RS<N>:` + `**Cover:**` shape, so agreeing on the content here but writing
it free-form still fails at the builder advance — see /apd-pipeline-guide.
Human gate YES also requires `**Evidence:**` per item.)
Risks: [concrete risks with mitigation — at least 1; especially for migration/security/auth tasks]
Rollback: [revert plan — revert commit + optional manual SQL/DROP if migration]
Mode: [Full | Lean]
R-criteria: [N items, listed R1, R2, ...]
Human gate: [YES/NO]
Ready to write the spec-card.md?
Risks + Rollback are NOT optional fields for tasks involving:
- Database migration (ALTER/CREATE/DROP)
- New public endpoint (security surface)
- Auth/role/permission changes
- External API integration
For trivial polish/hotfix tasks (1-2 R, no DB, no new endpoint), Risks can be "minimal — see Out of scope" and Rollback can be "revert commit". Be explicit anyway — empty Risks/Rollback in spec-card.md is a documentation gap that adversarial reviewer cannot catch.
5. Hand Off
Do not advance the pipeline while asking questions, presenting options, or
revising the design. Once the user explicitly approves the design summary:
- Load
/apd-pipeline-guide — the mandatory pipeline operating manual. It
carries the gate contract (plan format, rationale format, BLOCK recovery)
and writes the .guide-marker the spec gate requires.
- Write spec-card.md and call
apd pipeline spec "<name>" — the only valid
exit from brainstorming.
Do NOT write code during brainstorming. Do NOT advance the pipeline mid-flow
while questions or design choices are still open. This skill produces a
DESIGN, then exits only by advancing the approved spec. Code comes from
Builder agents after the spec is approved.
Red Flags — STOP
| Thought | Reality |
|---|
| "This is simple enough, skip brainstorm" | Simple tasks have hidden complexity. 5 minutes of questions saves 30 minutes of rework. |
| "I already know what they want" | You know what YOU would build. Ask what THEY want. |
| "Let me just start coding and iterate" | Iteration without direction is waste. Design first. |
| "The user seems impatient" | Users are more impatient when you build the wrong thing. |
| "I'll figure it out during implementation" | Builder agents follow specs. Vague specs produce vague code. |
Rules
- One question at a time
- Listen more than propose
- Present trade-offs, don't decide for the user
- No code during brainstorming
- No pipeline advance while asking questions, presenting options, or revising the design
- End with a clear design that feeds into the spec
Exit criteria
You're done when:
- The user can restate the goal in one sentence and you both agree on it
- Scope and out-of-scope are explicit and written down
- Approach is named (architectural pattern, library choice, integration point)
- Affected files are listed (not just "wherever it goes")
- The user has explicitly approved the design summary — no implicit approval
/apd-pipeline-guide has been loaded, the spec-card.md has been written and pipeline-advance spec "<name>" has been called as the final brainstorm action
Hand-off
- After explicit approval → load
/apd-pipeline-guide, write the spec-card.md and call pipeline-advance spec "<name>"; this is not a mid-brainstorm advance, it is the only valid exit
- Never leads to: code, agents, implementation — those come from the builder phase
- If the user asks for "just one quick thing" mid-brainstorm → finish the brainstorm first, then queue it
