agentsclimarketplace

Rewrite vs refactor

Skill Amey-Thakur/AI-SKILLS/skills/code-quality/rewrite-vs-refactor

Plug-and-play skills and prompts for every AI coding agent

Install
npx -y skills add Amey-Thakur/AI-SKILLS --skill rewrite-vs-refactor

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

2 things to look at

  • 19 days oldThe repository was created 19 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.
  • 4 stars4 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

Decide whether to refactor code in place or rewrite it from scratch using risk math, not frustration. Use when a component feels beyond repair and someone proposes starting over.

SKILL.md

3.0 KB, as published. Nobody here has run it

Rewrite vs refactor

The urge to rewrite is usually the code punishing you for not understanding it yet. A rewrite trades a known, working system for an unknown one, and the old system keeps shipping features while the replacement plays catch-up. Choose with numbers, not with disgust.

Method

  1. Start from refactor and make rewrite earn the switch. In-place refactoring keeps the system green and shippable at every step. Reach for a rewrite only when the constraint is structural: a data model that cannot represent the new requirement, a framework two majors past support, or a runtime you can no longer hire engineers for.
  2. Do the risk math on paper. Estimate rewrite effort, then multiply by 3 for the requirements buried in the old code that nobody wrote down. Add the freeze cost: the months the old system stagnates while the team builds its replacement. Compare that against refactor effort plus the interest of living with the mess. If rewrite does not win by 2x, refactor.
  3. Inventory the hidden behavior before you commit. Grep the old code for special cases: if branches on customer names, date cutoffs, retry counts, and workaround comments. Each is an undocumented requirement a rewrite must re-derive from scratch. A module dense with these is costly to refactor and lethal to rewrite blind.
  4. If rewriting, migrate with a strangler fig. Put the new code behind the old interface, route one endpoint or one entity type through it at a time, and delete the old path only after the new one carries production traffic. Never run a big-bang rewrite in a long-lived branch: it drifts from the shipping system and the merge never lands.
  5. Dual-run to prove equivalence. Send real traffic to both paths, compare outputs, and log every divergence (the GitHub Scientist pattern makes this cheap). Cut over only after divergences shrink to explainable rounding.
  6. Write kill criteria before the first commit. Decide up front what result reverts the effort: "if migrating module one takes over 6 weeks, we stop and refactor instead." A rewrite with no abort condition becomes a sunk-cost march that no one can call off.

Litmus tests

  • Can you name the exact structural constraint refactoring cannot fix? If not, you want a rewrite for how the code feels, and feelings are cheaper to fix.
  • Does the plan keep the old system shipping features the whole way through?
  • Is there a defined checkpoint where you would cut losses and stop?

Boundaries

This weighs one component's fate, not architecture strategy. When the question is how services split or which boundaries to draw, defer to system design. When the code is small enough that a rewrite fits in a day and a single review, skip the math and just do it.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.