/plan-a-change

name: "plan-a-change"
description: >
  Plans an architecture-driven change to code that already exists: module boundaries, type responsibilities, layering,
  coupling, and the public surface a revision moves. Produces a buildable change plan that names the types, modules, and
  methods involved and records the surface delta each change makes. Use when the user wants to plan, scope, or sequence
  a restructure, extraction, split, consolidation, responsibility shift, or API revision of existing code, including
  "these responsibilities are wrong, plan the fix". Does not assess an area and stop at findings — use
  architectural-analysis. Does not specify new behavior — use plan-a-feature. Does not diagnose a bug — use investigate.
  Does not write the code — use refactor to restructure it or tdd to build it.
arguments: size
argument-hint: "[size: small | medium | large | dynamic] [what needs to change, optional: source findings path]"
allowed-tools:
  Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(git *), Bash(mkdir *),
  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

• **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](./references/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](../../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](../../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](../../references/scope-justification-rule.md).

• **YAGNI gates every part the change introduces.** Apply [../../references/yagni-rule.md](../../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](../../references/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](../../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 fi