Use refactor-plan

Plan paying down one piece of technical debt as a refactor that serves the goal it is blocking

Plan paying down one piece of technical debt as a refactor that serves the goal it is blocking — characterisation tests on the riskiest behaviour first, then small steps each merged to main with main releasable after every one, pure refactors kept apart from the behaviour changes the goal needs, a scope fence, a stop point, a technique per step (extract, branch by abstraction, parallel change, strangler fig, mikado) and the clashes with in-flight feature work.

Reach for it when the user asks for a refactor plan, how to untangle, break up, replace or clean up a module without a rewrite, how to pay down a tech-debt item, "how do we refactor X without stopping feature work", "how do we get off X without a big bang", or wants a strangler-fig or mikado plan.

Install it

npx skilldrop-cli install refactor-plan                 # Claude Code, your user folder
npx skilldrop-cli install refactor-plan --project       # Claude Code, this repo
npx skilldrop-cli install refactor-plan --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Dev team pack: --pack dev-team installs it with its neighbours.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

• "This 1,800-line OrderService is where every change goes wrong; plan how we untangle it without stopping feature work"
• "TD-04 got approved for this quarter. Plan the refactor as small PRs we can ship one at a time"
• "How do we break billing's dependency on the web package without a big-bang rewrite?"
• "Give me a strangler-fig plan for replacing our legacy report builder module piece by piece"
• "We want to stop calling the SMTP client from 14 places — plan the refactor with characterisation tests first"

Requests like these belong to a different skill, so it shouldn't answer them:

• "Go through our TODOs and incident notes and tell me which tech debt to pay down this quarter"
• "Plan the cutover from MySQL to Postgres with a backfill and no downtime"
• "Implement step 2 of the refactor plan: move calculate_tax into its own module with tests"

If another skill answers instead, ask for this one by name: "use refactor-plan".

Check what you get

A good result:

• The first two lines give the approach and the first step. A chat question gets a chat-sized plan; a document only when asked or large.
• Every step serves the stated goal, and the last step reaches the structure that goal needs.
• Every step is labelled refactor or behaviour change; behaviour changes stand alone, after the refactor that makes them safe.
• Characterisation tests come first, on the incident-prone behaviour, and no open PR leaves that behaviour unpinned.
• Caller contracts, copies outside the module and real test coverage are reported from the files, cited file:function.
• Every in-flight clash has a decision, and a must-land feature PR is never blocked.
• The scope fence and stop point exist; new findings go to the register.
• Every file, function, metric and number is from the input. Unknowns are checks to run.

See a worked example

• search ranker

Use something else when

• Listing or ranking the debt in the first place — tech-debt-register
• Moving data, changing a schema or switching platforms with a backfill — migration-plan
• Writing the code for one of the steps — feature-implement-loop
• Deciding the target architecture or recording why — adr-generator or design-doc
• Reviewing a refactor PR that already exists — pre-merge-review
• Splitting a feature into user stories — user-story-splitter

Where a loop runs it

• Stage plan of the modernize loop

Next

• SKILL.md, the instructions the agent reads
• Its page on the site
• Related: adr-generator, design-doc, feature-implement-loop, migration-plan, pre-merge-review, tech-debt-register, user-story-splitter

Edit this page on GitHub · View source