plan-a-phased-build

## Project Context

- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`

## Operating Principles

- **Plain language is the default surface.** The build-phase outline never contains file paths, line numbers, function or class names, library mechanics, or language primitives. It uses product-level subsystem names ("the events processing system", "the database"), user-facing UI vocabulary (popover, modal, toast), behavioral verbs (publishes, retries, expires), and user-observable states. Brand names generalize one level up — "PostgreSQL" → "the database", "NATS JetStream" → "the events processing system". A non-technical stakeholder must be able to read the document end-to-end.
- **Every phase must be demonstrable to a real person.** "Demonstrable" means a person can be put in front of the running result and see something happen end-to-end — not "we shipped a service", but "you can do X and Y happens". If a phase is not demoable, it is either too small (merge it forward into the next phase that does become demoable) or too horizontal (it is a layer, not a slice — re-think it as a thinner end-to-end strip).
- **Every phase builds on the prior.** As phases ship, the system becomes progressively more capable. Earlier phases stay valid; later phases enrich what earlier ones delivered. Never sequence a phase so that it invalidates an earlier deliverable.
- **Vertical slices, not horizontal layers.** The first feature-shipping phase has every layer of the system involved end-to-end for one narrow scenario. A phase does not deliver "all the database work", "all the API surface", or "all the UI". Layered work that is not directly demoable on its own only justifies a phase when nothing demoable can ship without it (foundational/prerequisite phases — see next principle).
- **Foundational or prerequisite phases come first only when truly required.** If the demoable feature literally cannot run until a setting, permission model, schema, or configuration foundation exists, that foundation comes first — and even then the foundation phase must itself be demoable on its own (an admin can edit the new setting page and see the value persist, for example). If the foundation is not independently demoable, fold it into the first feature slice that uses it.
- **Traceability back to source is non-negotiable.** Every phase cites the section(s) of the source artifact that drove it. The reader can always answer "where did this phase come from?" without leaving the document.
- **Save incrementally — never lose work.** Write the outline file as soon as the executive summary and phase index are drafted, then update the file every time a phase is fleshed out. Do not buffer the entire document in conversation memory and write at the end. If the project is a git repo and the user has asked for it, commit between phase writes.
- **YAGNI is a first-class operating principle.** Apply the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md). A phase, foundation, precondition, or open question must show evidence of demoable user value, a hard dependency another in-scope phase requires, or an applicable regulation/measured signal. Phases that exist only for "completeness", "future flexibility", "best practice says we should", or symmetry with another effort fail the evidence test and go straight to the deferred-phases list with the reopening trigger named. Foundational phases must additionally cite the specific later phase that requires them — foundations with no downstream evidence get demoted to deferrals. Apply the simpler-version test: when evidence justifies a phase, ask whether a strictly thinner end-to-end slice (or merging into an adjacent phase) satisfies the same evidence; if yes, prefer the thinner slice. Every committed phase is delivery cost the team will pay.
- **All sub-agents in this skill run on sonnet.** When launching any Agent tool call in this skill, pass `model: "sonnet"`.

# Plan a Phased Build

## Step 1: Capture the Source Context and Output Location

Read the user's argument and conversation context to identify two things:

1. **The source context** — the body of information that will be split into phases. May be:
   - A single file path (gap analysis, PRD, design doc, feature spec, ADR, requirements list).
   - A folder path (multiple related documents to be considered together).
   - Inline conversation context (the user described what they want phased without pointing to a file).
   - A combination of the above.

2. **Shaping context** — anything the user said about *how* to phase the work that is not in the source. This typically includes goals that diverge from the source ("we need to add X that v1 didn't have"), explicit deferrals ("don't include URL shortening yet"), a target audience ("phase this for a stakeholder readout"), or constraints ("we can't ship anything that touches auth before Q3").

If the request is too thin to start (e.g., just "phase this"), ask the user — in one short message — for: (a) what artifact or context they want phased, and (b) any goals, deferrals, or constraints that should shape the sequencing. Do not ask about the output location yet.

Resolve the output location:
- If the user specified a folder path, use it.
- If the user pointed at a source file, default to writing the outline next to the source file (same folder).
- Otherwise, propose a folder name of **2 to 4 words** in kebab-case (e.g., `docs/plans/share-feature/`, `docs/roadmap/billing-rebuild/`). Prefer placing it under an existing documentation root surfaced via CLAUDE.md, `project-discovery.md`, or Glob fallbacks (`docs/plans/`, `docs/roadmap/`, `docs/`).
- Confirm the folder with the user in one short line before creating files.

The skill writes one file:

- `{folder}/build-phase-outline.md` — the primary outline, plain language, the only output the user will read.

If