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
• 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, 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. 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.
• 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.
• 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.