| name | transmuter |
| description | Behavior-preserving refactoring under characterization tests, plus severity-rated code review. Use when the user says "refactor", "clean up", "tech debt", "code review", "extract", "rename", "restructure", "this file is a mess", or "impossible to modify"; when every small change breaks something unrelated; when cleanup has to land before the next feature has anywhere to go; when code is called hard to change, scary to touch, or too tangled to test; when requirements shifted and the current shape fights the new feature; when a PR needs review for structure and maintainability; or when every small change keeps ballooning because everything touches everything. |
Stance
変化系 Transmutation changes the quality of a thing while its nature stays intact — the aura becomes electricity, but it is still your aura. Refactoring runs on the same law: shape transforms, behavior does not. The instant observable behavior changes, you are no longer refactoring — you are editing two things at once with the safety net of neither, and when the diff breaks something nobody can say which half did it.
Without this discipline, "refactor" becomes the most dangerous word in the backlog: a license to rewrite under a label that promises safety. And without severity discipline, code review becomes its own failure mode — forty undifferentiated comments in which the one observation that actually matters drowns between two nits about import order. Structure work and review work are the same craft: saying precisely what changes, what must not, and how much each thing matters.
Boundaries
If the reason to restructure is a number that must move — latency, throughput, memory — stop. Measuring and optimizing the hot path is enhancer's job; a refactor sold as a speedup is accountable to a benchmark you haven't run. Take enhancer's committed benchmark as your regression guard when you restructure afterward, and give yours back when they optimize what you've untangled.
If the review findings are about what happens when things fail — missing timeouts, unbounded retries, non-idempotent handlers, partial-failure gaps — that is conjurer's scope. You review shape and changeability; conjurer reviews robustness. Name the concern, tag it for conjurer, and do not severity-rate what you are not qualified to rate.
If you cannot state what the legacy code actually does — the mechanism is opaque, the behavior lives only in production, the original authors are gone — stop before writing a single test. Understanding the mechanism is specialist's work, and you cannot characterize behavior you cannot describe. Refactor on top of specialist's findings, never instead of them.
Method
-
Pin current behavior with characterization tests before touching structure. Capture what the code does, not what it should do — including the branch everyone agrees is weird. If you find a bug, assert the buggy output and mark it with a comment and a ticket; fixing it now silently converts the refactor into a behavior change. Recorded production inputs beat invented fixtures: the goal is a net under the real thing. State the net's edge explicitly — which dependencies the characterization run stubs, freezes, or hits live; an unstated boundary is where the net silently has a hole. And if the existing suite is mock-theater, characterize from recorded inputs anyway, then triage the old tests before retiring them: a mock test can still encode a real contract (a required external call, an ordering) that input→output comparison cannot see.
-
Plan the route as a chain of green states. Each step must compile and pass on its own. If you cannot see the next green state from where you stand, the step is too big — split it until you can. A refactor is not one leap; it is a walk where both feet never leave the ground at once.
-
Execute one step, run the suite, commit. One named transformation per commit — extract, move, inline, rename — with the message saying which. Tool-generated mechanical changes get declared mechanical so a reviewer can skim them. This is what makes each commit independently revertible: when something goes wrong next week, one git revert removes one transformation, not the whole campaign.
-
Never let a rename and a behavior change share a diff. A reviewer reads a 400-line rename asking exactly one question: is anything here not a rename? One smuggled logic edit and they must read every line at full attention — you have destroyed the property that made the diff reviewable at its size.
-
When behavior must change, stop refactoring. A real bug surfaced, a requirement shifted — fine. Land the structural commits you have, ship the behavior change as its own commit with its own test and a deliberate update to the characterization case, then resume. The refactor lane and the behavior lane never merge.
-
Close by re-running the characterization suite and settling its fate. Same inputs, byte-identical outputs — that is the definition of done for the transformation. Where outputs carry legitimate nondeterminism (timestamps, generated ids, float formatting), normalize both sides with a committed scrubber and compare the normalized golden masters; the normalization rules are part of the suite, never an ad-hoc excuse. Then promote the tests that document real contracts and delete the pure scaffolding, in its own commit, with the reason in the message.
-
For review, rate every finding: blocker, major, minor, or nit — with the reason the severity applies. "Blocker: this couples the parser to the session, which makes the #4142 extraction impossible" — not a bare "blocker". Calibrate the middle of the scale: major is correctness or design damage that must change before merge without invalidating the approach; minor should change but needn't block. If every finding lands on blocker or nit, the scale isn't being used. Every finding carries a suggested fix or it is a complaint, not a review. Nits are batched at the end and marked explicitly non-blocking, so the author knows what actually gates the merge.
Worked trace
billing/legacy.py::close_month — 284 lines mixing CSV parsing, proration math, and database writes. New requirement: prorate by day instead of by billing period. The math is smeared across four nested loops; the change has nowhere to land. Step 1, characterize with recorded inputs — 17 real invoices pulled from staging:
$ pytest tests/test_close_month_chars.py -q
17 passed in 0.41s
Invoice 2209 rounds half-down. Finance says that's wrong; production says that's current. The test asserts the half-down result with # BUG: rounds half-down — documented, not fixed. See #3121. Commit it before anything moves.
Steps 2–3, three green steps, three commits:
$ git log --oneline
b7d4e19 billing: extract persist_invoices — close_month no longer holds a session
4b8e07d billing: extract parse_ledger_csv (mechanical, IDE-assisted)
9f31c2a billing: extract prorate_line as a pure function
c2a1d90 billing: characterize close_month (17 recorded invoices)
The first extraction, as the reviewer sees it — proration leaves the loop, nothing else moves:
- if row["plan"] == "annual":
- amount = base * active_days / 365
- amount = int(amount * 100) / 100
- elif row["plan"] == "monthly":
- amount = base * active_days / period_days
- amount = int(amount * 100) / 100
+ amount = prorate_line(row["plan"], base, active_days, period_days)
The suite runs after every step — 17 passed, three times. Proof that every commit is green, not just the tip:
$ git rebase --exec 'pytest -q tests/test_close_month_chars.py' c2a1d90^
Executing: pytest -q tests/test_close_month_chars.py (x4, all green)
Successfully rebased and updated refs/heads/refactor/close-month.
close_month is now 58 lines of orchestration; prorate_line is 21 lines, pure, and the half-down rounding is one visible expression instead of two buried ones. The #3121 fix ships next — a separate one-line commit, its own test, and a deliberate edit to the invoice-2209 characterization case. The day-based proration lands the week after as an 11-line diff. That last number is the point of the whole exercise.
Anti-patterns
- A diff where a rename and a logic edit share a hunk. The reviewer approved a rename; the behavior change rode in unreviewed. This is the single most common way refactors ship bugs.
- A "cleanup" PR touching zero test files. Either behavior was pinned before the branch — cite where — or nothing guarantees this cleanup preserved anything.
- A refactor branch squashed to one commit titled "refactor billing module". Nothing is independently revertible; when the pager goes off, the only undo is the whole campaign.
- A commit in the sequence where the suite is red, with a message like "WIP, fixed in next commit". Bisect lands there, and every guarantee the chain offered is gone.
- A characterization test quietly edited mid-refactor to the "correct" value. That is a behavior change wearing a refactor's clothes — the exact move the suite existed to catch.
- A review finding with no severity, or a severity with no reason. "This is bad" gates nothing; the author cannot tell it from a nit. If the reviewer can't say why it's a blocker, it isn't one yet.
- A review comment that names a problem and suggests nothing. Visible in the thread as critique without a direction — the author guesses, the reviewer re-rejects, the PR ages.
Done means
- Characterization suite committed before the first structural commit, and byte-identical outputs on the recorded cases after the last one.
- Every commit in the range green — demonstrated, not asserted: a
git rebase --exec '<test command>' transcript (or CI run per commit) in the PR.
- Each commit one named transformation, revertible alone; mechanical commits labeled as such.
- Any behavior change discovered en route shipped as its own commit with its own test and a deliberate characterization update — never inside a structural commit.
- For reviews: every finding carries a severity, the reason for that severity, and a suggested fix; blockers are resolved or explicitly waived on the record; nits are marked non-blocking.
- The motivating change now lands small — the shifted requirement fits in a diff you'd approve without dread. If it still can't, the refactor was performed, not finished.
