Write an item that a maintainer can verify

Use a concrete statement such as “discount calculation differs between checkout and renewal” rather than “checkout is messy.” Link the affected code, a failed test or a recent incident in your team’s own register.

Keep evidence separate from the proposed solution. The same symptom may have several causes. An investigation item should say what uncertainty it will resolve before somebody commits to an expensive rewrite.

Add the fields that make a decision possible

Extend the working sheet with an owner, status, effort range and revisit trigger when your team needs them. Include a bounded scope and explicit exclusions so the repair can be reviewed against a stable agreement.

For prioritisation, record both impact and frequency. A severe but unlikely failure and an everyday delay need different discussion. Do not multiply arbitrary scores and present the result as a measured monetary value.

Keep accepted debt visible

Use statuses such as investigate, planned, in progress, accepted and closed. Close an item only when the acceptance evidence exists. Link the final commit or operational check to the original problem.

An accepted item stays in the register with its decision owner and revisit trigger. Review it when the product enters the affected area, a dependency loses support or observed harm changes. A register without decisions is only an inventory.

Working sheet

Illustrative technical debt register — replace before use
Problem and evidenceBounded repairAcceptance check
Checkout and renewal apply discounts differently; compare fixture totalsExtract the shared calculation; leave UI unchangedBoth recorded totals and boundary cases match
Import retries create duplicate fixture recordsAdd idempotency at the import boundaryRepeated fixture produces one logical record
Release smoke check depends on a shared test accountCreate isolated test data for that journeyTwo parallel runs complete independently
Critical module has no clear reviewerAssign owner and document its public contractA second maintainer reproduces the documented checks
Download this worksheet (CSV)

Questions about technical debt register template

Can we add cost estimates?

Yes, if the source and assumptions are visible. Use effort ranges and distinguish an observed recurring cost from a guessed future cost. Do not imply false precision.

How much detail belongs in one row?

Enough to decide and verify: evidence, impact, bounded action and acceptance check. Link longer incident notes or design documents rather than copying them into every cell.

How should I use the working sheet?

Download the CSV and replace the sample rows with evidence from your repository. Record a clear acceptance check and an owner for each item. Keep unresolved assumptions visible rather than treating the example as a completed assessment.

Sources and further reading

Examples are illustrative. They are not customer results, security guarantees, or a substitute for checking the documentation for your installed version.

Make the next change verifiable.

Getzilla is an open source workflow for changes to existing repositories. Inspect the project, define acceptance checks, and keep independent review in the loop.

See the repository workflow See current access and pricing