| name | apd-brainstorm |
| description | Use BEFORE writing the APD spec-card.md and calling apd:apd_advance_pipeline('spec', ...) on Codex whenever the task is vague, broad, ambiguous, or has multiple reasonable interpretations. Ask ONE question at a time, present 2-3 approaches when there are real choices, converge on a design the user explicitly approves. Works hand in hand with `.apd/rules/brainstorm.md` when that file exists. Triggers on "improve X", "what should we", "thinking about", "options", "not sure", "vague", "broad", "redesign", any task 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. |
APD Brainstorm (Codex)
Finish the question / option / design-approval flow BEFORE calling
apd:apd_advance_pipeline('spec', ...). That call is the only valid exit
after the user explicitly approves the design summary.
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 or the user 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
- Mid-pipeline (spec locked; raise concerns, 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.
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-card.md. A vague spec produces vague code.
Process
-
Read project context — AGENTS.md, .apd/memory/MEMORY.md and
.apd/memory/status.md, source close to the idea.
-
Ask ONE question at a time. Never dump a list of 5 questions. Ask
one, wait for the answer, ask the next.
-
Present trade-offs, do not decide. When real choices exist, offer
2–3 concise options and let the user pick.
-
Converge on a design. Hand the user a short summary covering Goal /
Scope / Out of scope / Approach / Affected files / Regression surface
(what this touches INDIRECTLY that must not break; 'none — reason' if
self-contained) / Risks / Rollback / Mode / R-criteria / Human gate.
Write the regression surface in the shape the gate parses — one
- RS<N>: <behaviour> — **Cover:** <existing suite | new test | none: reason>
per item, plus **Evidence:** per item when Human gate is YES. Agreeing on
the content but writing it free-form still fails at the builder advance;
the full contract is in apd-pipeline-guide.
Wait for explicit approval.
Risks + Rollback are NOT optional for tasks with DB migration / new
public endpoint / auth changes / external API. For trivial polish/hotfix,
say "minimal" or "revert commit" — but be explicit. Empty Risks/Rollback
in spec-card.md is documentation gap adversarial cannot catch.
-
Only then hand off: load apd-pipeline-guide (the mandatory pipeline
operating manual — gate contract + .guide-marker the spec gate requires),
write .apd/pipeline/spec-card.md, and call
apd:apd_advance_pipeline('spec', '<name>').
Do not do during brainstorming
- Write code
- Call
apd:apd_guard_write
- Edit any file outside
.apd/pipeline/
- Advance the pipeline while asking questions, presenting options, or revising
the design; the spec advance is allowed only after explicit approval and is
the only valid exit
Brainstorming produces a DESIGN. Implementation is the builder phase.
Red flags — STOP and return to Ask-One-Question
| Thought | Reality |
|---|
| "This is simple, 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. |
| "The user seems impatient" | Users are more impatient when you build the wrong thing. |
| "I'll figure it out during implementation" | Vague specs produce vague code. |
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, .apd/pipeline/spec-card.md has been written and apd:apd_advance_pipeline('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 apd:apd_advance_pipeline('spec', '<name>'); this is not a mid-brainstorm advance, it is the only valid exit
- Never leads to: code, agent edits, file writes outside
.apd/pipeline/ — those come from the builder phase
- If the user asks for "just one quick thing" mid-brainstorm → finish the brainstorm first, then queue it
