---
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

1. **Read project context** — `AGENTS.md`, `.apd/memory/MEMORY.md` and
   `.apd/memory/status.md`, source close to the idea.
2. **Ask ONE question at a time.** Never dump a list of 5 questions. Ask
   one, wait for the answer, ask the next.
3. **Present trade-offs, do not decide.** When real choices exist, offer
   2–3 concise options and let the user pick.
4. **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.
5. **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