Help with TD: A Practical Guide to Managing Technical Debt

Technical debt (TD) is not a moral failure. It's the accumulated distance between what your code is and what it needs to become. Help with TD usually starts with a blunt question: are we dealing with prudent trade-offs or reckless shortcuts?

What TD actually means

Martin Fowler's Technical Debt Quadrant splits debt along two axes: deliberate vs inadvertent and prudent vs reckless. Deliberate-prudent debt is a loan: you ship a thin integration now, document the assumptions, and schedule cleanup. Inadvertent-reckless debt is the dangerous kind: nobody knows why the module exists, tests are missing, and every change triggers a new incident.

In web-centric developer tools, TD often hides in:

Build pipelines that take 20 minutes and fail flakily.

Shared API clients with no versioning.

Test suites that prove little but cost a lot.

Deployment scripts that require one person's local machine.

Make TD visible before you try to fix it

A TD conversation that starts in code review will end in blame. A TD conversation that starts with data will end in a plan.

Instrument the following signals:

**Change failure rate** and **mean time to recovery** from DORA.

**Code churn** and **hotspot analysis**: files changed in every release are usually debt magnets.

**Review latency** and **CI duration**: slow feedback loops encourage larger, riskier merges.

**Incident frequency by service or area**: repeated incidents are debt revealing itself as unplanned work.

At Sapior, we treat these signals as product telemetry. When a team can see that one service accounts for 60% of hotfixes, the TD discussion shifts from subjective to obvious.

Prioritize debt like financial debt

Not all TD deserves repayment. Use an interest-rate lens:

**High interest**: every release requires manual workarounds; new hires cannot safely modify the area; failures are frequent and costly.

**Medium interest**: the area is ugly but stable; changes are slower but not dangerous.

**Low interest**: legacy code that works, is rarely touched, and is well-covered by tests.

Pay high-interest debt first. For code you touch frequently, refactor as part of the feature work. For code you rarely touch, leave it alone until there is a business reason.

Repay TD in small, continuous slices

Full rewrites rarely fix the underlying decision-making that created TD. They also pause product investment for quarters and often reproduce the same pressure under a new label.

A more reliable pattern:

1. **Define a debt budget.** For example, 10-20% of each sprint for refactoring, test hardening, or pipeline fixes.

2. **Scope refactors by blast radius.** Use code owners, dependency graphs, and test coverage maps to pick isolated seams.

3. **Automate the preconditions.** Lint rules, architecture tests, and required CI checks can prevent new debt from entering the same area.

4. **Review every incident for a debt decision.** Ask: was this caused by an earlier shortcut we accepted? If yes, file and prioritize it.

What help with TD looks like as a system

The goal isn't zero TD. That's impossible and often not economical. The goal is a system where TD is intentional, visible, and reversible.

When a team asks for help with TD, provide them with:

A dashboard of delivery and code health signals.

A lightweight debt register: what the shortcut was, when it was made, what it costs, and what repayment looks like.

A policy that new features touching high-debt areas must include a small cleanup task.

That turns an emotional argument into an engineering decision—and it's how durable developer-tools teams keep shipping without being owned by their past decisions.