- Home
- Skills
- Code Quality & Review
- Migration and Refactor Playbook
More screenshots
Works with the AI Agents you already use
Migration and Refactor Playbook
Safe large-scale code change: score the risk to pick atomic, incremental, or strangler; lock behavior with characterization tests; move in revertable steps; verify parity, not just green.
$5
Migration and Refactor Playbook
Example session with this skill installed
We need to swap our home-grown CSV export library for a maintained one. About 40 call sites use it, test coverage is patchy, and the exports are user-facing. Give me the plan before anyone touches code.
- Read your context and instructions
- Compiled the migration and refactor
Strategy scored before any code moves: consumers 2 (roughly 40 call sites), test coverage 1 (patchy), I/O 1 (file output at most sites), production criticality 1 (user-facing, not the revenue path), concurrent editors 0. Total 5 — incremental, with a wrapper seam. Not atomic: too many consumers for one commit. Not a full strangler: one library, one clean boundary.
Phase 1, map (no behavior changes): trace all 40 call sites and collapse them by export shape — expect a handful of distinct shapes, not forty. Document the old library's quirks explicitly; hand-rolled exporters always have them (quoting rules, empty-field handling, line endings), and at least one consumer somewhere depends on each.
Phase 2, lock behavior: one characterization test per export shape, written against the current library, asserting the quirks as-is and marking the deliberate ones. These commit before any swap work begins. They are the contract the rest of the migration must satisfy — and the reason "patchy coverage" stops being an objection.
Phase 3, steps, each green and revertable: (1) introduce a project-owned export interface wrapping the old library; (2) migrate call sites to the interface in small commits grouped by shape; (3) swap the implementation behind the interface to the maintained library in a single commit; (4) diff outputs, old against new, over a corpus of real exports, and reconcile every difference inside the adapter; (5) delete the old library and the wrapper options it forced.
Rollback at any step is a revert; before step 5 the old path is always one revert away. Victory condition, stated now so nobody declares it early: old library deleted, parity diff clean, export latency flat. "Code merged" is not on the list.
Connects securely to your tools. The creator never sees your data.
About this skill
Every large refactor is a bet that the new structure behaves exactly like the old one — and most teams place that bet with no map, no behavioral contract, and steps too big to revert. This playbook turns the bet into a procedure. It starts from two currencies every step must preserve: behavior (the system does the same thing after the step) and reversibility (the step can be undone in minutes). Lose either one and you are not refactoring; you are rewriting and hoping.
Strategy is chosen by measurement, not ambition: five risk signals — consumer count, test coverage, shared state and I/O, production criticality, concurrent editors — are each scored 0–2, and the total selects atomic, incremental, or strangler/expand-contract, recorded in writing so the choice is not re-argued at every hard step. Before any structure moves, you map every consumer and the real public surface, then lock current behavior with characterization tests that assert what the code actually does, quirks included — a quirk someone depends on is a feature until proven otherwise.
Execution runs as a chain of small, green, revertable commits using a catalog of proven moves: parallel implementations, adapter seams, one consumer at a time, expand-contract for schemas and APIs, delete-last for old code. Verification is parity, not just passing tests — old and new run against the same inputs and their outputs are diffed, production metrics are watched, and the edges tests skip (empty, huge, concurrent, timezone boundaries) are checked deliberately. The don't list and the completion gate make "done" mean the old code is deleted, the flags are gone, and the metrics are flat.
The playbook preserves behavior — including behavior that is wrong. Characterization tests lock quirks in deliberately; fixing them is separate, later work, and mixing the two is the exact failure the method exists to prevent. It also cannot manufacture safety where no verification is possible: code with no test runner and no observable outputs gets a step-zero tooling phase, and a handful of areas (timing-sensitive, hardware-coupled) may only ever reach partial parity evidence, which the plan states openly. Finally, it is slower than a rewrite on day one — deliberately. The cost buys revertability at every step; if your change is genuinely small and well-tested, the skill's own scoring will tell you to skip the ceremony and do it atomically.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 24 days ago
Permissions
No special permissions declared or detected