Refactoring Tech Debt Standards

Refactoring and technical debt standards

Criteria verified as of August 2026. Re-verify on the web before committing to anything (§8).

1. Scope and triggers

Covers the road from the code you have to the design you want: what is debt and what is not, how it is recorded, how it is prioritised, how it is funded, and with which techniques it is paid down without breaking the system. Triggers: "technical debt", "refactor", "refactoring", "legacy code", "code smell", "characterization test", "golden master", "strangler fig", "branch by abstraction", "expand/contract", "parallel change", "rewrite", "big rewrite", "hotspot", "cyclomatic complexity", "maintainability index", "SonarQube", "CodeScene", "debt register", "boy scout rule".

Guiding principle — technical debt is a financial metaphor and it is only useful if it is used as one. It has a principal (the work of fixing it), interest (the extra cost you pay on every change while it is not fixed) and a decision to pay it down taken by comparing the two. If you cannot name the interest you are paying, you do not have debt: you have an opinion about the code. Hard corollary: "debt" is not a synonym for "code I do not like", nor for "old code", nor for "the previous team's style".

Not applicable:

• software-architecture-patterns-standards (reciprocal: theirs the destination — which style, which boundaries, which pattern and which force justifies it; here the road — how you get there without breaking anything). Shared warning: migrating to a new pattern without tests is swapping one debt for a bigger one.
• testing-qa-standards (already written — it is the precondition of this skill: the test strategy, the pyramid, the coverage criteria and test quality are theirs; here only the non-negotiable requirement to cover the behaviour before touching it and the characterization technique for legacy).
• code-review-standards (already written: mechanics and criteria of review; from this side we fix that a refactor and a functional change are not reviewed the same way and do not go in the same commit — a refactor is reviewed against "is the behaviour still the same?", a functional change against "is the new behaviour correct?").
• git-workflow-standards (change size, branches, history, commit mechanics).
• vulnerability-management-standards (theirs the dependency CVEs, risk-based triage and EOL; here the debt of not having updated as a decision with growing interest).
• opensource-licensing-standards (a dependency that relicenses creates debt with an expiry date — its legal criteria belong to that skill; here, the record and the deadline).
• cicd-standards (the quality gate that is executed and how it is executed).
• tech-leadership-standards (the investment decision and its corporate record), project-management-standards (how the work is funded, planned and negotiated with stakeholders).
• legacy-modernization-standards (reciprocal: theirs the decision of what to do with an entire system —the "R" of the model, the archaeology of the platform, the routing to the skill for each inherited technology—; here the techniques with which it is executed: strangler fig, branch by abstraction, expand/contract, characterization before touching. A vocabulary warning that both uphold: the "R" for refactor in that model is not refactoring — there it means redesign, here it means changing the structure without changing observable behaviour).
• migration-projects-standards (theirs the cutover: rehearsal, window, rollback and shutdown of the old system; here what is done with the code in the meantime).
• Rewrite arbitration: when legacy-modernization-standards decides rebuild, the exceptional conditions that authorise it are those in §6.2 of this skill and they must be verified one by one. If they are not met, the answer is incremental refactoring, not a rewrite.
• performance-engineering-standards (optimising is not refactoring: optimisation changes observable characteristics and often deliberately worsens readability. It is measured, justified and reviewed separately).

2. Default decisions

Verify the latest version, licence and price on the web before pinning it in a real project (§8).

2.1 The metaphor, correctly attributed and correctly used

• Origin: Ward Cunningham, "The WyCash Portfolio Management System", OOPSLA '92 experience report (Addendum to the Proceedings, pp. 29–30, DOI 10.1145/157709.157715; text at c2.com/doc/oopsla92.html). His formulation: shipping code first time is like going into debt — a little debt speeds up development as long as it is paid back promptly with a rewrite; the danger lies in not paying it back, because every minute spent on not-quite-right code counts as interest. Attribution nuance: in the text Cunningham develops the debt-and-interest metaphor; the "technical debt" label was consolidated later.
  • What Cunningham did NOT say: that debt means deliberately writing badly. His debt is the mismatch between what the code expresses and what is now understood about the domain — debt from learning, not from botching. Using his quote to justify haste is a misrepresentation.
• Quadrant: Martin Fowler, bliki "Technical Debt Quadrant", 14 Oct 2009. Two axes: deliberate vs inadvertent (did we know we were taking it on?) and prudent vs reckless (was it a reasoned decision?):
  • Deliberate and prudent: "we have to ship now and we accept the consequences" — legitimate if it is recorded (§5).
  • Deliberate and reckless: "we do not have time for design" — that is not debt, it is damage.
  • Inadvertent and prudent: "now we know how we should have done it" — unavoidable in any good team; it is Cunningham's.
  • Inadvertent and reckless: "what is this layering thing?" — solved with training, not with a backlog.
  • The Fowler observation worth retaining: the useful distinction is not between debt and non-debt, but between deliberate and inadvertent debt.
• Operational consequence: every register entry (§5) declares its quadrant. Reckless ones are not "managed": the cause is cut off (review, training, CI gate). Prudent ones are managed as real debt: principal, interest, trigger.

3. Refactoring: definition, precondition and mechanics

3.1 Canonical definition (verbatim) and its consequence

Martin Fowler, Refactoring: Improving the Design of Existing Code (definitions also published at refactoring.com):

"noun: a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior"

"verb: to restructure software by applying a series of refactorings without changing its observable behavior"

Fowler specifies that "observable behavior" is deliberately imprecise: the code must do, broadly, the same as before; the call stack changes with an extract function and performance may vary — nothing the user cares about must change.

Non-negotiable consequences:

• A refactor that changes behaviour is a functional change in disguise and it is reviewed, tested and deployed as such. Labelling it "refactor" so that it gets less scrutiny is a process failure, not a naming detail.
• Refactoring ≠ restructuring ≠ optimising ≠ rewriting. Fowler uses "restructuring" as the general term; performance optimisation often worsens readability on purpose, and that is why it is not refactoring (→ performance-engineering-standards).
• A PR titled "refactor" with 40 files and a bug fix inside is unreviewable: nobody can tell what changed from what moved.

3.2 The non-negotiable precondition

Without tests covering the affected behaviour, you are not refactoring: you are rewriting blind. The test is the only thing that turns "I changed the structure" into "I did not change the behaviour". The criteria and quality of those tests belong to testing-qa-standards; what is fixed here is that they exist before the first change.

Legacy without tests — reference work and terminology: Michael Feathers, Working Effectively with Legacy Code (2004). His operational definition, deliberately uncomfortable: legacy code is "code without tests" (not "old code"): without tests there is no way to verify that it still does what it did. Consequence: you can write legacy code today.

Procedure when there are no tests:

1. Characterise first. A characterization test (term coined by Feathers; also golden master) "is a test that characterizes the actual behavior of a piece of code": it documents the real behaviour, not the one you wish it had. Mechanics from the book: write an assertion you know will fail, read the real value in the failure output and pin it.
2. Bugs are characterised too. If the current behaviour is incorrect, it is pinned as-is and noted; fixing it is a separate functional change, with its own decision and its own commit.
3. Find the cut point (seam) so you can instantiate and isolate the unit; break the dependency with the smallest possible intervention (the safest one first: extract and inject, do not redesign).
4. Only then refactor, in small steps.
5. For large migrations with tangled dependencies, the Mikado Method (Ola Ellnestam and Daniel Brolund, Manning, 2014) gives an explicit procedure: attempt the change, note what breaks as a prerequisite, revert, and attack the leaves of the graph. The key is that you revert: the tree is discovered with the system always green.

3.3 Mechanics: order, tooling and step size

• Safe order: first what the tool can do on its own (rename, extract, move, change signature), then what requires judgement (extract class, break a dependency, change the model). Never the other way round.
• Automated refactor > manual whenever it exists: the IDE preserves references and does not miss usages. Watch the blind spots: reflection, magic strings, injection by name, embedded SQL, templates, external configuration — there a "safe rename" is not safe.
• Step size is the safety criterion, not speed. Rule: if after the step you cannot run the tests and see them green, the step was too big. The worse you know the code, the smaller the step.
• One commit per green step, with a message saying which transformation it is. A readable refactoring history is what lets you bisect when something broke three weeks later.
• Two-hats rule: at any moment you are either adding functionality or refactoring, never both. If while refactoring you find a bug, note it and carry on; you fix it afterwards, in its own commit.

4. What gets paid: interest, heat maps and the metrics trap

4.1 Prioritise by interest, not by age or by ugliness

Ugly code nobody touches costs nothing. A horrible module, stable, with no incidents and no changes in two years has interest ≈ 0: refactoring it is pure expense and on top of that it introduces risk. The debt that gets paid is the one that charges interest:

Interest ≈ change frequency × difficulty of changing × failure impact.

Signals of real interest, all observable:

• Change heat map: commit frequency per file/module in the Git history, crossed with the difficulty of changing that code. Activity concentrates in a few modules: there, and only there, poor quality is paid for every week.
• Change coupling: files that always change together without being related by design (a signal of a badly placed boundary → software-architecture-patterns-standards).
• Defect density and resolution time per module.
• Cycle time of the changes that touch that area, compared with the average.
• Bus factor: if only one person can touch it, the interest includes the risk of them leaving.

4.2 The metrics trap

Aggregate metrics give a feeling of objectivity and replace the conversation. Real status of the two most cited ones:

• Cyclomatic complexity (McCabe): published and unrefuted criticism.
  • Shepperd, M. (1988), "A critique of cyclomatic complexity as a software metric", Software Engineering Journal (IET, DOI 10.1049/sej.1988.0003): poor theoretical foundations and, for much software, it is no more than a proxy for lines of code, often outperformed by them.
  • Jay, G. et al. (2009), "Cyclomatic Complexity and Lines of Code: Empirical Evidence of a Stable Linear Relationship" (JSEA): a stable and practically perfect linear relationship between CC and LOC, verified over more than 1.2 million files; they conclude that CC adds no explanatory power of its own beyond size.
  • Permitted use: a local threshold as a smell that opens a conversation about a specific function. Forbidden use: as a quality KPI, as a team target or as a debt prioritisation criterion.
• Maintainability index (MI) (Oman & Hagemeister, 1992): worse. It is a weighted combination of Halstead volume, cyclomatic complexity, LOC and comment ratio; it inherits CC's problem and adds its own.
  • Arie van Deursen, "Think Twice Before Using the Maintainability Index" (2014): originated in an internal HP project with 16 projects rated by eye and dozens of regression models; the original authors proposed it for relative comparisons within the same team, a warning systematically ignored.
  • Tooling criticism (Teamscale, among others): different tools compute different values because they tweak the formula, and the developer cannot predict how their change will affect it — extracting a method lowers complexity but raises LOC, so improving the code can worsen the index. It also averages and hides the real distribution.
  • Criteria: the MI is not used to decide anything.
• General rule: a metric works as a signal that opens an investigation, never as a target (the moment it is a target, the metric gets optimised instead of the code). Measuring quality by a single index is forbidden.

4.3 Tools (verify licence and price, §8)

• The stack's linter and formatter, in CI and blocking: it is 80 % of the value for 0 % of the cost, and it removes the style argument from review.
• Architecture fitness functions (ArchUnit — Apache-2.0 — and equivalents) so that the structure does not erode while you pay down debt. The criteria for which rule to write belong to software-architecture-patterns-standards.
• SonarQube: it is not simply "open source". Since 29 Nov 2024 the SonarQube Community Build binary (formerly Community Edition) remains under LGPLv3, but the bundled analysers moved to the Sonar Source-Available License v1 (SSALv1), a source-available licence with a competitive-use restriction — it is not open source under the OSI definition. Community Build does not analyse branches or decorate PRs: that is the paywall. Commercial editions are billed per line of code, not per user, so the cost grows with the size of the repository. Verify current pricing with the vendor before quoting it: the figures circulating on blogs are third-party and diverge from each other.
• Semgrep: open source CLI engine (LGPL-2.1, copyleft — relevant if you package a product); the cloud platform is paid per contributor and the rates published by third parties contradict each other ($35 vs $40+ per contributor/month depending on the source): confirm with the vendor.
• CodeScene: behavioural analysis over the Git history (hotspots, change coupling, function-level X-Ray, Code Health metric). It is the category that best fits §4.1. Commercial product and proprietary metric: its supporting studies are authored by its founder and use its own metric — a conflict of interest that must be declared before citing them as independent evidence.
• Cross-cutting rule: no tool decides which debt gets paid. They produce candidates; the decision is human and goes into the register (§5).

5. The debt register (§5 substituted: "stack security" would be artificial in a process domain — security appears here as dependency debt and as a prioritisation criterion, and its management belongs to vulnerability-management-standards)

A debt entry that cannot be acted on is noise. Minimum fields, and all mandatory:

Rules:

• Debt with no owner and no date does not exist: it is closed or deleted. A register that only grows is a graveyard and after six months nobody opens it.
• The trigger is what prevents the graveyard register. Useful forms: "when we touch this module for the third time", "before adding the second payment provider", "when version X reaches EOL (date)", "if the cycle time of this area exceeds N".
• Debt lives in the same backlog as the rest of the work and competes for priority with data, not in a parallel document no planning session ever looks at.
• TODO/FIXME in the code are not a register: they are notes. If something matters, it is recorded with an owner; if not, it is deleted. A TODO from 2019 is a signed lie.
• Deliberate and prudent debt ⇒ recorded in the same PR that takes it on, with its reason. That is the only moment when the context is fresh.

6. Large-scale strategies and funding (operability of change)

6.1 Strategies, with verified attribution

• Strangler fig — Martin Fowler, "Strangler Application", 29 Jun 2004, later renamed to "Strangler Fig Application" (the original text is preserved at OriginalStranglerFigApplication.html). The metaphor is taken from the strangler figs of the Queensland rainforest. Idea: grow the new system at the edges of the old one, diverting traffic feature by feature until the old one can be retired. Requirements: an interception point (facade, proxy, routing) and usage telemetry to know when the old one is no longer used. Retiring the old code is part of the task, not future debt.
• Branch by abstraction — Paul Hammant documented and named the term in 2007 (crediting the coinage to Stacy Curl); Hammant is explicit that he did not invent it, it was a known practice without a name. Jez Humble and Martin Fowler popularised it later with real cases. Attributing the origin jointly to Hammant and Humble is incorrect. Idea: introduce an abstraction over the current provider, migrate clients so that they only talk to it, implement the new provider behind it, switch over, and remove the abstraction if it no longer adds anything. It is the alternative to a long-lived branch: it lets you ship while the big change is half done.
• Expand/contract (parallel change) — the canonical reference is Danilo Sato, bliki "ParallelChange" on martinfowler.com, 13 May 2014; the name "expand and contract" comes from the world of schema evolution (Refactoring Databases, Scott Ambler and Pramod Sadalage). Three phases: expand (add the new without removing the old) → migrate (move all consumers) → contract (retire the old).
  • For a database schema: never rename or drop in the same release that deploys the code; new column, dual write, backfill, read from the new one, and drop the old one in a later release with usage already at zero.
  • For an API: the new coexists with the old, usage is measured per consumer and it is retired with a communicated deadline (contract governance belongs to api-design-standards / microservices-architecture-standards).
  • The contract phase is mandatory and must be planned. An expand/contract that never contracts has doubled the debt with permission.

6.2 Why a full rewrite is almost always the worst option

Classic reference: Joel Spolsky, "Things You Should Never Do, Part I", 6 Apr 2000, written in the wake of Netscape 6, which he calls "the single worst strategic mistake that any software company can make: They decided to rewrite the code from scratch". It is an argument, not data: it is cited for its reasoning, not as empirical evidence.

Reasons that hold up:

• The old code contains years of fixes for real cases that are not documented anywhere else. The rewrite loses them and rediscovers them in production, one by one.
• During the rewrite there are two systems to maintain and new functionality frozen; the business rarely tolerates that freeze, so the old one keeps growing and the finish line recedes.
• The new team usually underestimates the domain, not the technology: the hard part was not the framework.
• It is big bang: risk is concentrated in a single cutover, with no intermediate feedback and no realistic way back.

Exceptional conditions in which it can indeed be the right option (all verified, and in an ADR — software-architecture-patterns-standards):

• The base platform is dead or unsupported and there is no migration path (discontinued runtime/language/vendor with no way out).
• The system is small and its behaviour is specified or reproducible (it can be characterised in full and outputs compared in parallel).
• There is nobody who can modify it and acquiring the knowledge is not viable (the code is already a de facto black box).
• The new requirement is incompatible at its core with the current model (e.g. multi-tenancy or regulation that cuts across the whole data model) and the cost of adapting exceeds that of redoing it, calculated, not guessed.
• Even so: do it in parts with strangler fig and parallel run comparing outputs, not as a single cutover.

6.3 How the work is funded

Three models; they are combined, not chosen exclusively. Negotiation and planning belong to project-management-standards.

• Boy scout rule: "leave the code better than you found it", adapted to software by Robert C. Martin in Clean Code (2008) from the scouting motto — popularisation and adaptation, not invention: the campsite formulation is much older. Operational limit: the opportunistic improvement must not bloat the diff of the functional change (it clashes with code-review-standards). If it does not fit in the same PR in a reviewable way, it goes in its own refactor PR, before or after.
• Why the dedicated "cleanup" project usually fails: it delivers no visible value for months, so it is the first to be cancelled when the business squeezes; it freezes or duplicates the product team's work; it is measured by work done and not by interest eliminated, so it tends to clean what is easy instead of what is expensive; and it ends up being a covert rewrite with the risks of §6.2. If it is done: closed scope, incremental deliverable every few weeks, a measurable success criterion over interest (§4.1) and an end date.
• Honest negotiation rule: argue with interest, not with morality. "This module is touched in 3 out of 4 iterations and each change costs twice the average" convinces; "the code is dirty" does not, and rightly so.

7. Debt that is not code, sustainability and prohibitions

Debt does not live only in the code. These categories are recorded the same way (§5) and usually have growing interest and a hard date:

• Dependencies not updated: the cost of skipping N versions grows faster than linearly. Default: continuous, automated updating (dependency bot) with CI that validates it; the big jump is avoided, not planned. CVEs and their triage belong to vulnerability-management-standards.
• Versions out of support (EOL): it is the only debt with a date known in advance; it enters the register with the trigger set on the day the end-of-support calendar is published, not the day it expires.
• A dependency's licence change: relicensing upstream (to source-available or strong copyleft) turns a harmless dependency into debt with a deadline. Detecting it requires reading the raw LICENSE, not the README. Legal criteria: opensource-licensing-standards.
• Non-reproducible infrastructure: pet servers, manual configuration, environments that only work on one machine. The interest is charged in full on the day of the incident.
• Knowledge in a single head: it is debt with a total-default risk. It is amortised with cross-review, rotation, documentation of the why and pairing on the critical module.
• Test debt: a slow suite (nobody runs it), flaky tests (nobody believes them), coverage concentrated on the trivial and absent on the critical, tests coupled to the implementation (they prevent refactoring — the worst of all, because it blocks paying down the rest of the debt). The criteria for what a good test is belong to testing-qa-standards.
• Process and data debt: manual deployments, absence of a tested rollback, historical data with incompatible schemas.

List of prohibitions

• ❌ FORBIDDEN to call anything "debt": without principal, observable interest and a declared consequence, it is a style preference. And style is solved by the formatter, not by the backlog.
• ❌ FORBIDDEN to refactor without tests covering the affected behaviour. If they do not exist, characterise first (§3.2).
• ❌ FORBIDDEN to mix refactor and functional change in the same commit (and, except in trivial cases, in the same PR): they are reviewed with different criteria and together they are unreviewable.
• ❌ Labelling as "refactor" a change that alters observable behaviour.
• ❌ Full rewrite as the default answer, or without meeting and documenting the exceptional criteria of §6.2.
• ❌ Measuring quality by a single index (cyclomatic complexity, maintainability index, coverage, debt in a tool's "days") or turning it into a team target.
• ❌ Using the maintainability index to decide priorities (§4.2).
• ❌ Prioritising debt by age, by ugliness or by tool score instead of by measured interest.
• ❌ Refactoring stable code nobody touches "while we are at it" (risk with no return).
• ❌ Debt entries without an owner, without a trigger or without a review date.
• ❌ TODO/FIXME with no associated issue as a substitute for the register.
• ❌ A long-lived refactor branch in parallel to the development one (use branch by abstraction; see git-workflow-standards).
• ❌ Expand/contract without the contract phase planned and executed.
• ❌ Fixing a bug discovered during characterisation inside the same commit: the real behaviour is pinned and the fix goes separately.
• ❌ Migrating to a new pattern or architecture without tests: it is swapping one debt for a bigger one (reciprocal of software-architecture-patterns-standards).
• ❌ Citing figures from this domain without a primary study and methodology (§8).

8. Mandatory web verification

Before committing anything from this document to a real deliverable, verify with WebSearch/WebFetch (the data is from August 2026):

1. SonarQube: current licence of the Community Build binary (LGPLv3 as of this date) and of the analysers (SSALv1 since 29 Nov 2024) read at sonarsource.com/license/ and in the repository's raw LICENSE; what is left out of Community Build (branch analysis, PR decoration); current prices confirmed with the vendor — third-party blog tables are estimates and contradict each other. Same for Semgrep (LGPL-2.1 for the CLI; cloud rates disputed between sources) and for CodeScene (commercial; its price is not clearly published).
2. ArchUnit and per-stack equivalents: version and licence from the raw LICENSE, not from aggregators (MvnRepository lists licences mixed in from bundled dependencies).
3. Status of the methodological criticisms in §4.2 (Shepperd 1988; Jay et al. 2009; van Deursen 2014): check whether a later refutation exists before relying on them. As of Aug 2026 none has been located.
4. Bibliography and attributions: date and canonical URL for Fowler (TechnicalDebtQuadrant, StranglerFigApplication), Sato (ParallelChange), Hammant (Branch by Abstraction), Cunningham (OOPSLA '92) and the current edition of Fowler's Refactoring and Feathers' Working Effectively with Legacy Code. An incorrect attribution is a factual error.
5. EOL of the dependencies you declare as debt with a date: endoflife.date and the project's official source. api.github.com returns 403 unauthenticated: for a repository's activity, use the website or the Atom feed of releases.

Declared gap (no research budget in this draft) — pending verification before use:

• Cost figures for technical debt: no primary study with sound methodology has been located that would allow asserting a percentage of development time lost to poor quality. Discarded for lack of a primary source: the "10×/100× cost of fixing a defect by phase" (the trail dies in internal IBM notes from 1981 via Pressman; documented by Bossavit, The Leprechauns of Software Engineering) and the "80 % of lifecycle cost is maintenance" (it entered the literature as an informal estimate cited in Lientz & Swanson, not as a measurement). Declared discrepancy: the widely circulated "up to 42 % of developers' time wasted" comes from vendor surveys, not from measurement; the Code Red study (Tornhill & Borg, TechDebt 2022, DOI 10.1145/3524843.3528091) is indeed peer-reviewed and with a replication package, but it uses the proprietary metric of the tool belonging to one of its authors — cite it declaring that conflict of interest, or do not cite it.
• Concrete thresholds for any metric (complexity, size, coverage): they are deliberately not fixed here; any number adopted must be justified against your own code base, not copied.

If the web contradicts this document, the web wins — flag the discrepancy.