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. 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 build-phase-outline.md already exists in the chosen folder, ask the user whether to overwrite, append a timestamp suffix, or stop. Do not silently overwrite.

Step 2: Read the Source and Project Context

Before asking the user shaping questions, read every source artifact identified in Step 1. For each file, capture:

• The structure (top-level headings) so phases can cite specific sections.
• Any existing inventory of capabilities, gaps, or features the user expects phased.
• Any prior decisions, open questions, or recommendations already recorded.

Also read the lightweight project context:

• CLAUDE.md and any project-discovery.md if they exist — they may surface conventions for where this kind of document lives, what tone the team uses, or what other planning docs already exist.
• Existing planning/phasing/roadmap documents in the chosen output folder or its parent (use Glob) — the team's prior format precedent informs the reading-experience choices in Step 6.

Record what was found and what was not. The document does not need to cite project context, but the discovery shapes recommendations later.

Step 3: Interview the User for Shaping Context

For every decision the source artifact does not already settle, surface a focused question to the user with a recommended answer. Do not batch every question upfront — ask as the structure unfolds. Typical decisions that need user input:

1. Goal of the build outline — what does "fully shipped" look like? Is it parity with a prior version, satisfaction of a PRD, achievement of a metric, or something else?
2. What's new compared to the source. The source artifact often describes the prior state. The user may want behaviors that diverge from it — capture those explicitly. Each divergence needs a name so it can be referenced from individual phase write-ups (e.g., "role-based authorization replaces the v1 hardcoded read-only model").
3. Explicit deferrals. Anything the user wants visible at the botto