Engineering leaders rarely lack a backlog of “debt” tickets. What they lack is a shareable plan that ranks which debts to repay this quarter, how much capacity each item needs, and what to do if a fix goes wrong. A quarterly tech debt roadmap answers that scheduling problem with scored axes and explicit rollback notes — as decision-support, not as a certificate that the codebase is healthy.
Ward Cunningham’s debt metaphor framed short-term delivery choices as obligations that accrue interest in the form of slower change later. Martin Fowler later organized common pathways into a Technical Debt Quadrant — deliberate versus inadvertent, reckless versus prudent. That matrix is useful in planning meetings because it separates “we chose a shortcut with a repay date” from “we skipped tests with no plan.”
ISO/IEC 25010 adds another shared language: product quality characteristics such as maintainability, reliability, and security. Mapping a debt item to those characteristics helps product and engineering agree which gaps deserve budget. The standard does not tell you which ticket to pick first; it reduces arguments about what “quality” means in your domain. See the ISO/IEC 25010 overview for the characteristic set.
Ticket-level debates stall when every team brings a different mental model. A practical middle layer is four axes scored 0–100, where higher means healthier:
Severity bands turn numbers into capacity language: Critical below 40, High below 60, Moderate below 75, Low below 90, Healthy at 90 and above. Targets are optional; drawing a second radar polygon makes “where we want to be by quarter end” visible without pretending the chart is a legal attestation.
| Axis | Typical evidence | Bad practice |
|---|---|---|
| Code | CPD/clone reports, cyclomatic complexity gates | Gut feel “it’s messy” |
| Architecture | ArchUnit / module import rules, context maps | Rename folders and call it a rewrite |
| Test | JaCoCo/Cobertura, CI flaky history | Invent a coverage percentage |
| Documentation | OpenAPI freshness, ADR presence | Promise “docs later” with no owner |
Each action row should carry four fields beyond the title:
Reckless debt often needs a process fix (definition of done, CI gates) in addition to a refactor ticket. Prudent deliberate debt usually needs a dated repay plan that leadership can see on a QBR slide. If an item has no rollback story, treat the risk column as incomplete rather than filling it with optimism.
Some teams reserve a fixed slice of each sprint for debt; others run a focused burn-down after incidents. Either approach works when the slice is visible and the selection criteria are stable. Avoid concentrating every quarter on a single perspective — only tests, or only “clean code” — while architecture coupling continues to tax every feature.
CVE Critical/High counts belong to dependency scanners (OWASP Dependency-Check, Snyk, Dependabot). Line or branch coverage belongs to reports under your build directory. Flaky rates belong to CI history. If those tools have not run, label the field needs scan/CI instead of inventing a number that will mislead capacity planning. Worked-example figures in sample playbooks are personas, not your repository.
A governance tool can turn pasted findings into a radar and a dated action list in minutes. An optional model-assisted narrative can explain ranking in plain English for stakeholders. Fail-closed behaviour matters: if the model key is missing, the API should return 503 rather than a fake success; live text should be labelled as model-assisted; deterministic free paths should never impersonate live AI.
What the tool must not claim: guaranteed remediation, 100% debt discovery, or that a rewrite is required. Those calls remain with the people who own the system.
Repeat the loop even when scores look “fine.” Prudent inadvertent debt appears as teams learn better designs — Fowler’s “now we know how we should have built it” cell. Catching that early is cheaper than waiting for an outage to force the conversation.
Imagine a payment service outage traced to a cross-module database read and a missing contract test. The architecture axis drops into Critical; the test axis follows. Code duplication in an unrelated parser stays Moderate. Documentation for the payment API is two releases stale. A single composite “debt score” would blur that story. Four axes make the sequencing obvious: stop illicit DB access, add a contract test on the failure path, then refresh the OpenAPI description so the next on-call engineer is not guessing.
Effort estimates in the action table should match how the team already plans — person-days or story points — so finance and engineering share one unit. Benefit statements should name the axis and the business outcome (“reduce failed checkouts during peak”) rather than vague “improve quality.” Risk notes call out migration windows and dual-write periods. Rollback notes say whether a feature flag, revert, or previous container tag restores service.
When presenting to leadership, show the radar first, then the three actions that fit remaining capacity. Leave other debt visible but deferred with an explicit “not this quarter” label. That honesty prevents the backlog from pretending everything is in flight.
Chasing only the loudest complaint creates thrash. A sales engineer’s frustration with docs can be real while architecture coupling silently doubles feature lead time. Another anti-pattern is rewriting modules because the radar looks angular — shape alone never proves a rewrite is cheaper than targeted boundaries. A third is inventing scanner metrics to fill empty cells; empty cells labelled needs scan are more trustworthy than fabricated coverage.
Teams also confuse activity with repayment. Merging style-only pull requests can improve aesthetics without moving any axis. If the action cannot state which axis improves and how you will re-measure, it probably belongs in continuous hygiene, not in the quarterly roadmap headline.
Persistent Critical scores often signal ownership gaps. An axis that stays Critical for two consecutive quarters usually needs a named owner, a CI gate, or a hiring plan — not only another refactor ticket. Document that meta-action beside the technical ones. Product managers should see debt capacity the same way they see feature capacity; otherwise the roadmap becomes a private engineering diary.
For regulated domains, map selected actions to the quality characteristics you care about under ISO/IEC 25010 vocabulary, and keep legal counsel out of the loop unless you are making compliance claims. This product does not issue compliance certificates; it helps you schedule engineering work with clearer trade-offs.
After paste, verify severity bands match your intuition on at least one axis you know well. If the chart disagrees wildly, fix the input evidence before debating capacity. The deterministic free path is designed for that loop without consuming AI quota.
Re-score within two weeks of finishing a Critical action, not only at quarter end. Early measurement catches actions that looked complete in the ticket tracker but never moved the axis. Capture the scanner command versions beside the new scores so the next auditor can reproduce the evidence trail. If the architecture axis stays flat after a “boundary fix,” inspect whether import rules were enforced in CI or only described in a wiki page.
Share the delta with product partners in the same format every time: previous score, new score, actions completed, actions deferred. Consistency builds trust faster than a polished one-off slide deck that disappears until the next crisis.
A dated set of remediation actions for the next quarter, each with estimated effort, expected benefit, risk, and a rollback note, tied to scored debt axes.
No. Scores are decision-support. Final remediation design still needs a qualified engineer.
From scanners and CI reports. Inventing Critical/High CVE counts or coverage percentages without evidence is incorrect practice.
Related: Security & honesty · Pricing · Tech debt radar guide