FREE TEMPLATE

Technical Debt Tracking Register

Four documents and four sheets, including the register column that says what each item is costing you per year in engineering hours.

Edit with AI Download (.docx + .csv)

Free download · No account needed

What you get

Pack of 8 files: 4 documents, 4 spreadsheets

Technical Debt Tracking Register

How Interest Is MeasuredDocument
Worked Example, Sedgemoor Funds Four ItemsDocument
Debt AssessmentDocument
Prioritisation RationaleDocument
Module Change ProfileSpreadsheet
Debt RegisterSpreadsheet
Change Failure CorrelationSpreadsheet
Remediation PlanSpreadsheet

Every debt register in circulation has the same columns: an ID, a description, a severity from one to five, an estimated effort, an owner, a status. It loses to the roadmap every quarter, and not because the engineers explained it badly. Severity and delivery weeks are not comparable quantities, so there is no honest way to put the register beside the feature list and choose. The column that would make them comparable is the one nobody fills in.

It has been named since 1992. In Ward Cunningham's original report on the debt metaphor, the definition is one sentence: every minute spent on not-quite-right code counts as interest on that debt. Not the cost of the rewrite. The tax on ordinary work while the rewrite has not happened. That is measurable from records you already keep, as the excess hours a module costs per change over the codebase median, times how often it actually changes.

Sedgemoor, the billing platform in the worked example, had 47 items and a severity column. Measured, 16 of them sat in code with no commit in twelve months, two of the team's own top four among them. Four of the ten most expensive modules in the codebase were not in the register at all. Invoice rendering, ranked seventh, cost 614 hours a year, more than the top three combined, because it changes 118 times a year and each change runs 5.2 hours over the median.

The register, re-ranked by what each item actually costs

Three sheets from one codebase. What each item costs per year, what it costs when a change goes wrong, and what fixing it returns.

Technical Debt Tracking Register

Debt RegisterChange Failure CorrelationRemediation Plan

Debt Register

Illustrative rows for a fictional B2B billing platform, Sedgemoor. Interest is the excess hours per change over the codebase median of 3.1, times the change count in twelve months.

Module	Severity rank	Changes, 12m	Hours per change	Interest, h/yr	Rank by interest
Invoice rendering	7	118	8.3	614	1
Tax rules engine	2	62	9.6	403	2
Subscription state machine	1	52	10.2	369	3
Webhook dispatch	not in the register	94	6.9	357	4
Legacy pricing tables	3	3	12.6	28	11
Currency conversion, old	5	1	11.4	8	13
Data import v1	4	0	not measurable	0	none

The severity column and the measured column disagree almost everywhere. Invoice rendering was ranked seventh and costs more per year than the top three combined, because it changes 118 times to their 52 and 62 and 3. Nothing about it felt urgent. Every single change to it was merely tedious.

Two of the team’s own top four are in code nobody touches. Legacy pricing tables had 3 changes in a year and data import v1 had none at all, so its interest is zero however bad the code is. Across the full 47-item register, 16 items sat in modules with no commit in twelve months.

Four of the ten most expensive modules in the codebase, carrying 780 hours a year between them, were not in the register at all. The largest was webhook dispatch, where every new event type needed edits in three places and nothing failed at compile time when one was missed.

Change Failure Correlation

The join against twelve months of incidents and reverted changes. This is the half of the argument a product manager already believes.

Module	Changes	Incidents	Reverted	Failure rate	Against baseline
Invoice rendering	118	3	17	14.4%	4.5x
Tax rules engine	62	0	8	12.9%	4.0x
Webhook dispatch	94	1	11	11.7%	3.7x
Subscription state machine	52	4	6	11.5%	3.6x
Auth middleware	77	1	4	5.2%	1.6x
Ledger posting	31	0	0	0.0%	unevidenced
ALL FLAGGED MODULES	619	9 items	14 items	11.8%	3.7x
ALL UNFLAGGED MODULES	1,104	none	none	3.2%	1.0x

The last two rows are the whole meeting. A change touching at least one flagged module was reverted or rolled back 11.8 percent of the time. A change touching nothing flagged, 3.2 percent. One ratio, 3.7 to one, computed from the team’s own merge history rather than from an industry report.

Thirty of the 47 items had neither an incident nor a failed change over a full year. They are relabelled unevidenced and left in the register rather than deleted. Deleting an entry starts an argument about the register. Relabelling one starts an argument about the evidence, and that argument has an answer.

Reverted changes are usually easier to extract than incidents, because they live entirely in version control. A revert, a rollback, or a fix change landing inside forty-eight hours and referencing the same work all count.

Remediation Plan

Interest is gross. The recovery fraction is the share of it the engineer giving the estimate will commit to removing, and it is the column that reorders this sheet.

Module	Fix hours	Interest	Recovery	Returns, h/yr	Payback
Webhook dispatch	120	357	60%	214	6.7 months
Invoice rendering	240	614	55%	338	8.5 months
Payment provider adapter	80	178	45%	80	12.0 months
Subscription state machine	200	369	50%	184	13.0 months
Tax rules engine	160	403	35%	141	13.6 months
Legacy pricing tables	120	28	70%	20	72.0 months
Data import v1	320	0	80%	0	never
FUNDED SET, four items	720	1,743	blended	877	9.9 months

The tax rules engine carries the second-highest interest and lands fifth. The engineer who would do the work would only commit to removing about a third of the excess, because the rest is the tax code and no refactor removes that. Nobody asks for this number, and it changes the order.

Data import v1 has no case at any fraction. Eighty percent of zero is zero. It had been ranked fourth by severity two years running, and the arithmetic retires the argument in one line rather than in another meeting.

The four funded items took 720 engineering hours and return 877 hours a year, a blended payback of 9.9 months. That is a proposal a product manager can compare against a feature, because both are denominated in the same unit.

Edit with AI

What's in the pack

Module Change Profile

Every module in the codebase with its change count, median hours per change, contributor churn and last commit date, whether or not the register mentions it.

Debt Register

Each item carrying a measured interest figure in hours per year, its old severity rank and its new rank, so the disagreement between the two stays visible.

Change Failure Correlation

The join against incidents and reverted changes, ending in one ratio: the change failure rate for code that touches a flagged module against code that does not.

Remediation Plan

The only sheet allowed to hold an estimate, with a recovery fraction beside each one, because a refactor rarely removes all of a module's excess cost.

How Interest Is Measured

The method, written so somebody who was not in the room can reproduce every figure, including what the measurement cannot see and why the incident join sits beside it.

Debt Assessment

The standing position: total interest as a share of team capacity, split by temperature, by evidence and by the mechanism that makes each change expensive.

Prioritisation Rationale

The document that goes into planning, opening with four numbers and containing a section naming the high-severity items that lost their rank once measured.

How to use it

1
Open in River, or take it blank
Send the pack twelve months of change history inside River, or download the four documents and four sheets and work through the method without an account.
2
Build the change profile first
One baseline figure for the whole codebase, then a change count and a cost per change for every module. Every interest figure is an excess over that baseline.
3
Rank everything, not just the register
Sort all modules by measured interest and compare against what somebody wrote down. The gap is usually the most useful output of the first pass.
4
Join, then cost, then ask
Attach incidents and reverted changes to each item, set a recovery fraction with the engineer who would do the work, and compute payback in months.

Frequently asked questions

Is this template free?

Yes, and the download needs no account and no card. Edit with AI is the optional half: it reads the change history and incident records you send, builds the module profile, and measures interest on every item. Every other pack sits in the template library.

What format are the downloaded files?

Four documents as Word files and four sheets as CSVs, in one zip. The Module Change Profile and Debt Register arrive with their columns ordered and the Sedgemoor rows in place as worked examples, so the arithmetic is visible before you replace them with your own.

We do not track engineering hours per change. Can we still use it?

Yes. Use elapsed time from first commit to merge on the pull requests touching each module, and label the column so nobody compares the two units. A consistent proxy everybody can see beats a scored guess. The ranking holds because every module is measured the same way.

Our static analysis tool already reports a technical debt figure.

That is a different quantity with a similar name. SonarQube's own definition sums a remediation cost attached to each rule that fired, over a cost to develop one line of code, thirty minutes by default, times the line count. Both terms are constants.

So why does that figure never move anybody?

Because neither term looks at the change history, it cannot fall when a module goes cold. At Sedgemoor, 41 percent of a reported 358 days sat in modules with no commit in twelve months. An accurate estimate of a cleanup nobody needed.

What about debt that is a risk rather than a cost?

An interest figure cannot see a danger that has not yet cost anything, and a rarely changed module handling money will sit near the bottom. That is why the incident join sits beside the interest column rather than replacing it. Make the risk argument separately, on its own terms.

What else belongs alongside this?

The measurements either side of it. Engineering metrics and delivery review covers throughput and change failure across the team, inherited codebase documentation maps a system nobody has context on, and postmortem action follow-through tracks what incidents were supposed to fix. The contributor guide is worth sending to whoever is about to touch one of these modules for the first time.

Sources

Written by

Chandler Supple

Co-founder & CEO, River

Chandler has spent the last six years working in AI, building tools for millions of users and Fortune 100 companies. In 2025, he co-founded River to build a new kind of operating system for AI agents.

LinkedIn GitHub X

Reviewed by

Brian Joseff, Co-founder, River

LinkedIn X

More free templates

API Deprecation Policy Template

Free API deprecation policy template: the notice list built from real usage, the callers you can actually reach, and a window derived from how often they ship.

API Documentation and Reference Template

Free API documentation template in Word and CSV, with the two registers a generator cannot produce: undeclared failures, and examples that do not validate.

Open Source Contributing Guide Template

Free contributing guide template built from your own closed-without-merging pull requests, split into what a checklist could have caught and what never could.

Partner Integration Guide Template

Free partner integration guide template built from real support tickets, split into what was already documented and what never was.

Put a number on the register that a product manager can argue with

Take the Word documents and CSV sheets blank, or open this exact pack in River and send it twelve months of change history.

Edit with AI

Technical Debt Tracking Register

The register, re-ranked by what each item actually costs

Debt Register

Change Failure Correlation

Remediation Plan

What's in the pack

Module Change Profile

Debt Register

Change Failure Correlation

Remediation Plan

How Interest Is Measured

Debt Assessment

Prioritisation Rationale

How to use it

Open in River, or take it blank

Build the change profile first

Rank everything, not just the register

Join, then cost, then ask

Frequently asked questions

Is this template free?

What format are the downloaded files?

We do not track engineering hours per change. Can we still use it?

Our static analysis tool already reports a technical debt figure.

So why does that figure never move anybody?

What about debt that is a risk rather than a cost?

What else belongs alongside this?

Sources

Chandler Supple

More free templates

Put a number on the register that a product manager can argue with