plan-a-change

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

• Code-level names are the subject of this plan, not a leak into it. Types, modules, files, methods, and public signatures are what the plan is about. A sibling skill forbids them because it specifies behavior a user observes; this one plans a structure an engineer works in, so name the thing. The altitude limit is different in kind: carry the names, the responsibilities, and the contracts between them, and never inline whole file bodies or prescribe line-level edits, BECAUSE the plan is executed after the codebase has moved on and the builder reads the current code at build time.
• The change is justified against a recorded reason, and the reason is not assumed. Step 1 reads the supplied context to establish why a change is being planned at all. A reported defect is one possible reason among several, and so is a prior findings report; neither is presumed to exist. With no reason recorded there is no evidence test to apply, so the run does not proceed to a plan.
• Behavior is preserved unless the plan says otherwise, entry by entry. An architecture-driven change moves responsibility between parts. Every entry in the surface delta is classified as behavior-preserving or behavior-changing at Step 6, and a behavior-changing entry cannot be committed silently.
• The surface delta is a target-state record, not migration advice. Every element the change removes, adds, moves, renames, or re-scopes carries a statement of what is true after the change, in its own right. Migration guidance is additional and never substitutes for it. Per surface-delta-rule.md.
• A contract two parts must independently agree on is pinned here, not invented during the build. Splitting one type's responsibilities across three creates contracts between them: a call signature, a payload shape, an error contract, a lifecycle order. Each is a decision-bearing value the plan carries in concrete form. See ../../references/contract-pinning-rule.md.
• The run stays inside the boundary it descends from. Step 1.5 records the work item's stated scope and exclusions, per ../../references/planning-boundary-rule.md. The scope gate at Step 8 reads that record. Anything the boundary excludes lands in a visible cut list, per ../../references/scope-justification-rule.md.
• YAGNI gates every part the change introduces. Apply ../../references/yagni-rule.md to each new type, interface, abstraction layer, extension point, configuration seam, and adapter the target state proposes. A new abstraction with one implementation and no named second caller is the signature failure of this skill's domain: it is the easiest thing to justify from taste and the hardest to remove later. Items failing the evidence test land in ## Deferred (YAGNI) with the reopening trigger named.
• Evidence quality is the companion principle. Apply evidence-rule.md alongside YAGNI. YAGNI gates whether a part is included; this one characterizes what each claim about the current code rests on.
• Questions to the user arrive one at a time, led by the consequence. Per ../../references/operator-escalation-rule.md. The Step 1.5 confirmation turn is the one exception, and the one turn that carries more than one ask.
• The plan lives in three cross-referenced files. change-plan.md is the deliverable and sits at the root of {folder}/; artifacts/change-decision-log.md and artifacts/current-state-findings.md sit beneath it. The plan cites decisions with inline ([D-N](artifacts/change-decision-log.md#...)) links and cites current-state evidence with ([C-N](artifacts/current-state-findings.md#...)) links. Any edit to one file updates the matching cross-reference fields in the others.