ahgraber Refactor: Behavior-Preserving Structural Change
Overview
Refactor changes the structure of working code; it does not change behavior.
It differs from simplify by risk rather than size: simplify applies edits whose behavior preservation is verifiable on the spot, and refactor takes the edits that are not — the ones that move contracts, cross module boundaries, or touch files far from where the request started.
Those need a plan the user rules on before anything lands, because the resulting diff is too large to review after the fact.
Every move is approved individually and executed on its own, with verification green between moves.
When to Use
- A function or class has grown past the point where it can be read.
- Two modules import each other, or a layer imports something below it that it must not.
- An abstraction has one implementation, and collapsing it touches every call site.
- A simplify pass left structural proposals and the user wants to work through them.
- Code needs to move: extracted to a new module, merged into an existing one, renamed across the tree.
When Not to Use
- Slop cleanup belongs to
simplify: duplication, dead code, comment noise, local de-nesting. - Judging a change belongs to
code-review: correctness, security, test adequacy, merge readiness. - A bug gets fixed first. Changing behavior is a different task, so fix it and then refactor the result.
- Refactor never adds capability. New behavior is a different task too.
- A rewrite that trades semantics for speed does not preserve behavior, so optimization work does not belong here.
- Anything a configured linter or formatter flags is out of scope. Run the tool.
Invocation Notice
- Tell the user when this skill is running:
refactor. Skip the notice when the user asked for the skill by name or slash command; spelling and spacing need not match. A phrase from this skill's own trigger list is not a name — naming the work is not naming the skill.
Phase 0 — Gate
1. Resolve the work
A proposal comes from one of three sources. Use whichever the request provides:
- A ledger.
The user points at a
.simplify/ledger-*.md(or says "work through the deferred items", in which case take the newest). Its Deferred section is the work list; each entry carries a proposed move, blast radius, and verification plan. If no ledger exists, say so and ask what to work on. - A report or finding list from a review or another agent. Treat each item as a proposal to validate, not a decision already made.
- A direct request: decompose this, split that.
Say once that a
simplifypass first usually shrinks the job, because dead code and duplication are cheaper to delete than to carry into a new structure. If the user declines, proceed.
The ledger format lives in the simplify skill's references/edit-ledger.md; read it when consuming or writing one.
If that file is not available, the sections are simple enough to mirror from any existing ledger: Applied, Removed, Deferred, Skipped.
2. Baseline
Find the repo's checks and establish the strongest available check:
- Full test suite with the target code exercised — confirm with coverage, not assumption.
- Typecheck plus lint, when no suite covers the target.
- Characterization test written first, pinning current behavior; it stays afterward as a regression guard.
- Stop. Below level 3 there is no way to demonstrate behavior preservation, and a refactor that cannot demonstrate it is a rewrite. Say so and let the user decide.
Run the baseline before any edit. If the suite is red, stop; without a green start, no later failure is attributable. Record the check, the command, and the result — and the starting commit, which Phase 3's scope check needs.
3. Specs
Look for a spec source: an openspec/ or specs/ tree, or artifacts from the sdd family.
Structural change must leave the code compliant.
If a move cannot preserve compliance, record it and stop.
Suggested spec revisions go in the ledger, and this skill never applies them.
4. Graph tooling
If the code-review-graph MCP plugin is available, call build_or_update_graph_tool() then list_graph_stats_tool().
If either call fails or the graph is empty, continue on the git-only path and do not retry.
See references/code-review-graph-integration.md for per-phase use.
The graph matters more here than in a review, because blast radius is what the plan is built from. Without it, establish the same facts by grep: every caller, importer, subclass, and test of what you are about to move — and every textual reference: strings, config keys, fixtures, serialized data.
Phase 1 — Plan (no edits)
Produce a plan before touching anything.
For each move, follow the procedure in references/structural-moves.md and record these fields:
| Field | What to record |
|---|---|
| Move | Which structural operation, on what |
| Preconditions | What must be true for the move to preserve behavior |
| Blast radius | Files touched, callers updated, tests affected, public surface changed |
| Test impact | Which tests must change, and why each is coupled to structure and not behavior |
| Verification | What proves behavior is unchanged, beyond a passing suite |
| Order | The sequence that leaves verification green between moves |
Count the blast radius; do not estimate it.
Split anything large into the smallest moves that each leave the tree green. One 900-line move is not a plan the user can rule on.
State what you are not doing. Do not widen the plan after approval. The user approved what you presented, not a larger version of it.
Phase 2 — Approval
Present the plan and stop.
The user approves moves individually, not the plan wholesale. They will often want two of six. Note declined moves in the ledger so the record shows they were considered.
Approval of a move covers the test changes its Test impact field enumerated; do not re-ask for those during execution.
Do not begin executing while asking.
Phase 3 — Execute
Take one approved move at a time, in the planned order.
For each move:
- Confirm verification is green.
- Make the move, and only that move. If you notice something else, put it in the ledger.
- Update every caller, importer, and subclass the plan identified.
- Run the check.
- If green, record the outcome and continue to the next move.
- If red, revert the move entirely. Do not repair forward. Record what failed and why, so the proposal is not blindly retried later.
If a test edit surfaces that the approved plan did not enumerate, stop and get agreement first, stating three things:
| State | What it means |
|---|---|
| What changed | The specific assertion, and what it asserted |
| Why it was coupled | What made it depend on structure and not on behavior |
| Why behavior is stable | What else proves the observable contract holds, now that this test no longer does |
A test edit that cannot supply all three is a behavior change, not a refactor. Revert it and say so.
If the blast radius exceeds the plan, stop and re-plan. Discovering three more call sites mid-move means the user approved a plan that was wrong.
Phase 4 — Record
If the work came from a ledger, append an outcome block under each executed entry: what changed, files touched, verification result, anything discovered. Note declined proposals. Add new Deferred entries for structural work this pass surfaced but did not do. If the work came from chat, write a fresh ledger for the pass instead (same format).
Rationale goes in the ledger, not the code. Do not leave comments narrating the restructuring.
Ledger IDs are ephemeral. T3 addresses an entry in one file.
It never appears in source, comments, commit messages, or PR descriptions.
Then report: moves executed, moves declined, net file and line movement, final verification result, ledger path, and what remains deferred.
References
references/structural-moves.md— the move catalog: preconditions, procedure, and verification for each operation.references/code-review-graph-integration.md— graph tool dispatch for blast-radius analysis and post-move verification.simplifyskill,references/edit-ledger.md— the ledger format this skill consumes and appends to.