/plan-a-phased-build

name: "plan-a-phased-build"
description: >
  Splits a body of context into a sequence of vertical-slice build phases where each phase is independently demonstrable
  to a real user and each builds on the previous. Use when the user wants to plan, sequence, phase, slice, break down,
  or order the build of a feature, capability, system, or initiative, and produces a plain-language phased build
  outline. Does not produce implementation detail — use plan-implementation. Does not specify behavior that has not been
  decided — use plan-a-feature. Does not perform gap analysis between two artifacts — use gap-analysis. Does not break a
  plan into independently-grabbable work items — use plan-work-items.
argument-hint: "[source context path or description, optional: output folder path, optional: shaping context]"
allowed-tools:
  Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(mkdir *), Bash(cp *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

• CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
• project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

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.

• **The run stays inside the boundary it descends from.** Before phasing anything, the skill records the work item's

stated scope and exclusions, plus whatever scope the user stated when invoking it, per [../../references/planning-boundary-rule.md](../../references/planning-boundary-rule.md). Every phase then names what it descends from, and a candidate that cannot name one goes to the deferred list as a scope cut rather than into the sequence. See [../../references/scope-justification-rule.md](../../references/scope-justification-rule.md).

• **Scope the user states out loud is part of the boundary.** This skill treats divergence from its source as a feature,

not a defect, and phasing a roadmap where the user wants something the source lacks is its normal case. A goal the user states is a boundary statement in its own right, recorded alongside the work item rather than checked against it.

• **One stop, and no escalation loop.** This skill has no escalation step and does not gain one. Questions that need a

decision land in the Open Questions section, where they already belong. The one exception is a single stop for an input only the user can supply, per [../../references/operator-escalation-rule.md](../../references/operator-escalation-rule.md).

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

[../../refe