Surgical refactoring

Skill pipipip169/fable5-handoff/sources/adamentwistle-fable-skills/surgical-refactoring

The retirement handoff of Claude Fable 5 - written by the model itself. Domain-neutral discipline files that transfer flagship working method to any model, any agent framework, any team.

Install

npx -y skills add pipipip169/fable5-handoff --skill surgical-refactoring

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

3 things to look at

25 days oldThe repository was created 25 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

3.0 KB, as published. Nobody here has run it

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.