| name | surgical-refactoring |
| description | Refactor/rename/migration discipline — enumerate all call sites before editing, separate mechanical from judgment edits, keep the build green, verify by absence and presence. Use for renames touching 3+ sites, signature/type reshapes, moving code, or codebase-wide pattern swaps. |
Surgical Refactoring
Refactors fail in predictable ways: missed call sites, half-migrated hybrid states, scope creep, and behavior changes smuggled in as "cleanup". The countermeasures are mechanical.
1. Enumerate every touch point BEFORE the first edit
Grep for the symbol/pattern with multiple casings and forms (fooBar, foo_bar, FooBar, string literals, dynamic access, re-exports, tests, docs, config). Count them. Write the list down. The refactor is done when that list is exhausted — not when the build passes, because dead branches, string-keyed lookups, and mock/stub twins compile fine while broken.
Special sweeps people miss: test fixtures, mock implementations that mirror real ones, serialized/persisted data keys, API contract strings, comments/docs, and anything reached by reflection or string dispatch.
2. Separate mechanical from judgment edits
Split the work: (a) purely mechanical transformations (rename, move, signature reshuffle) with zero behavior change, and (b) judgment edits (logic changes, improvements). Do them in separate passes — ideally separate commits. A diff that mixes both is unreviewable, and behavior bugs hide inside "just a rename".
If asked only to refactor: behavior must be bit-identical. Resist fixing bugs you find mid-refactor — note them and report them instead (fixing them silently changes behavior the user didn't ask to change).
3. Sequence to keep the build green
Order edits so the project compiles at every intermediate point where possible: introduce the new shape first (new function/type alongside old), migrate call sites in groups, then delete the old shape last. For breaking changes that can't overlap, do the full sweep in one atomic pass — never leave a session with half the call sites migrated.
4. Verify by absence AND presence
- Absence: grep the old name/pattern → zero hits (or a written justification per hit).
- Presence: the project's full gate suite (build/typecheck, lint, tests) after the last edit.
- Behavior: run whatever exercises the refactored path — a pure rename that passes tests can still break string-keyed runtime dispatch.
5. Scope is a contract
"While I'm here" is how a 5-file rename becomes a 40-file diff nobody asked for. Improvements you notice outside the requested scope go in your report as suggestions, not in the diff. The exception: changes strictly required to complete the requested refactor (a caller that must adapt).
When to stop and re-plan
If the sweep reveals 5× more call sites than expected, a public API boundary, or persisted-data implications (stored keys, wire formats, migrations needed) — stop and surface it. Those change the cost/risk profile the user approved.
