# Technical Debt Register: [Product, system or team]

> Register for recording, prioritising and paying down technical debt:
> a shared taxonomy (including Martin Fowler's technical debt quadrant),
> the register itself with interest, principal and a priority score, the
> triage process, the capacity budget for repayment and how progress is
> reported. Based on common engineering practice. Replace every
> `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Record debt when it is noticed, not when it hurts. A one-line entry is
  better than an undocumented shortcut.
- Estimate interest (what the debt costs you every month) as well as
  principal (what it costs to fix). Interest drives priority; principal
  alone favours easy fixes that may not matter.
- Review the register on a fixed cadence (section 4) and tie repayment to
  a capacity budget (section 5). A register without a budget is a list of
  regrets.
- Close entries when fixed, and also when the affected code is retired.
-->

| Field | Value |
|---|---|
| Register ID | [TDR-PRODUCT] |
| Scope | [Systems, repositories or services covered] |
| Owner | [@tech-lead] |
| Contributors | [Teams] |
| Review cadence | [e.g. Every two weeks in backlog refinement; quarterly summary] |
| Last reviewed | YYYY-MM-DD |
| Related | [Architecture description], [Fitness functions], [Risk register] |

## 1. Purpose and definitions

<!-- Guidance: Agree what counts as technical debt so the register does not fill up with feature requests or bugs. State the boundary in a sentence or two. -->

Technical debt is any design or implementation choice that makes future
change slower, riskier or more expensive than it needs to be, compared
with a reasonable alternative. Defects with user-visible impact go to
the bug tracker; missing features go to the product backlog. A debt
entry may reference either when they are a symptom.

| Term | Meaning in this register |
|---|---|
| Principal | Effort to remove the debt, in engineer-hours |
| Interest | Recurring extra cost the debt causes, in engineer-hours per month (slower changes, incidents, manual work, workarounds) |
| Risk factor | Multiplier from 1 to 3 for security, compliance or outage exposure not captured by interest |
| Payoff horizon | Period over which interest is counted when prioritising; *Example:* 12 months |

## 2. Debt taxonomy

<!-- Guidance: Classify each entry twice: by how it arose (the quadrant) and by where it lives (the category). The quadrant helps learning; the category helps routing to owners. -->

### 2.1 Technical debt quadrant

Martin Fowler's quadrant classifies debt by intent (deliberate or
inadvertent) and by judgement (prudent or reckless). The descriptions
below are written for this template.

| | Deliberate | Inadvertent |
|---|---|---|
| **Reckless** | The team knowingly skipped good practice with no plan to repay; *example:* no tests to hit a demo date and no follow-up ticket | The team did not know a better practice existed; *example:* hand-built SQL strings because nobody knew about parameterised queries |
| **Prudent** | The team chose a shortcut consciously, recorded it and planned repayment; *example:* single-region launch with a ticket to add a second region before scale-up | The team learned later what the design should have been; *example:* the domain model only became clear after a year in production |

Use the quadrant in retrospectives: reckless entries point to process or
skills gaps; prudent-inadvertent entries are a normal result of learning.

### 2.2 Categories

| Code | Category | Typical examples |
|---|---|---|
| ARC | Architecture | Tight coupling between services, shared database, missing boundaries |
| COD | Code | Duplication, very large classes, dead code, poor naming |
| TST | Test | Missing or flaky tests, slow suites, no contract tests |
| INF | Infrastructure | Manual provisioning, unpatched base images, snowflake servers |
| DEP | Dependencies | End-of-life frameworks, unmaintained libraries, pinned old versions |
| DOC | Documentation | Missing runbooks, outdated diagrams, undocumented APIs |
| SEC | Security | Hard-coded secrets, weak crypto, missing audit logging |
| DAT | Data | Unclear ownership, missing constraints, inconsistent schemas |

## 3. Register

<!-- Guidance: One row per debt item. Keep the description concrete enough that someone new can find it. Estimate interest and principal in the same unit. Recompute the priority score at each review. -->

### 3.1 Priority score

Priority compares the interest paid over the payoff horizon with the
cost of fixing, adjusted for risk:

$$
P = R \times \frac{I \times H}{C}
$$

where $I$ is interest in engineer-hours per month, $H$ is the payoff
horizon in months, $C$ is principal in engineer-hours and $R$ is the risk
factor (1 to 3). $P > 1$ means fixing the item is expected to pay back
within the horizon. Rank by $P$, then by due dates imposed by
compliance or end-of-life events.

*Example* for TD-001 with $H = 12$: $P = 1.5 \times \frac{16 \times 12}{80} = 1.5 \times 2.4 = 3.6$.

### 3.2 Register table

| ID | Description | Location | Quadrant / category | Impact | Interest $I$ (h/month) | Principal $C$ (h) | $R$ | Priority $P$ | Owner | Status |
|---|---|---|---|---|---|---|---|---|---|---|
| TD-001 | *Example:* Order and invoice services share one database schema; every schema change needs both teams | `orders-db`, services `order-svc`, `invoice-svc` | Prudent-inadvertent / ARC | Releases blocked twice a month | 16 | 80 | 1.5 | 3.6 | [@team-orders] | In progress |
| TD-002 | *Example:* Reporting module duplicates tax calculation logic | `reporting/tax.py` | Reckless-inadvertent / COD | Divergent totals found twice a year | 4 | 120 | 1.0 | 0.4 | [@team-finance] | Accepted (not now) |
| TD-003 | *Example:* Payment SDK version reaches end of support in 5 months | `payments/` | Prudent-deliberate / DEP | No security patches after end of support | 10 | 40 | 2.0 | 6.0 | [@team-payments] | Planned for sprint 42 |
| TD-004 | *Example:* Database password in a deployment script | `deploy/legacy.sh` | Reckless-deliberate / SEC | Credential exposure | 2 | 16 | 3.0 | 4.5 | [@platform] | Open |
| [TD-nnn] | [What and why it hurts] | [Path, service, component] | [Quadrant / code] | [Effect] | [h] | [h] | [1-3] | [P] | [@name] | [Open / Planned / In progress / Accepted / Closed] |

Arithmetic check for the examples: TD-002 $= 1.0 \times 48 / 120 = 0.4$;
TD-003 $= 2.0 \times 120 / 40 = 6.0$; TD-004 $= 3.0 \times 24 / 16 = 4.5$.

### 3.3 Status definitions

| Status | Meaning |
|---|---|
| Open | Recorded and estimated, not yet triaged |
| Planned | Accepted for repayment in a named iteration or quarter |
| In progress | Work has started; link the ticket |
| Accepted | Consciously left in place; review date set; reason recorded |
| Closed | Repaid or the affected code was retired; date and evidence recorded |

## 4. Triage process

<!-- Guidance: Describe who adds entries, who estimates, how often the register is reviewed, and how decisions are made. Keep it light enough that teams actually follow it. -->

1. **Capture.** Anyone adds an entry with a description, location and
   rough impact. Shortcuts taken deliberately during delivery are logged
   in the same pull request that introduces them.
2. **Estimate.** The owning team estimates interest and principal at the
   next refinement session. Use ranges when unsure and record the midpoint.
3. **Score.** Compute $P$ and set the risk factor. Security and
   compliance items with $R = 3$ are escalated to [@security-lead].
4. **Decide.** At the review, each item becomes Planned, Accepted with a
   review date, or is merged with another entry.
5. **Verify.** When closed, record the evidence (merged change, metric
   improvement, removed component).

| Trigger | Action |
|---|---|
| New item with $R = 3$ | Review within 5 working days |
| Item with $P \geq 3$ open for more than one quarter | Escalate to engineering manager |
| End-of-life date within 6 months | Plan regardless of $P$ |

## 5. Budget allocation

<!-- Guidance: State how much capacity goes to debt repayment and how it is protected. A fixed share of capacity works better than asking for permission item by item. -->

| Item | Value |
|---|---|
| Capacity share for debt repayment | *Example:* 20% of each iteration's planned capacity |
| Capacity this quarter | *Example:* 6 engineers x 60 days x 6 h x 20% = 432 engineer-hours |
| Allocation rule | *Example:* Highest $P$ first; at least one item with $R \geq 2$ per iteration |
| Exceptions | *Example:* Budget may be lent to a release for at most one iteration and is repaid in the next |
| Approver for changes | [@engineering-manager] |

Planned use this quarter: [list the items and hours]. *Example:* TD-003
(40 h), TD-004 (16 h), TD-001 (80 h), leaving 296 h for items raised
during the quarter.

## 6. Reporting

<!-- Guidance: Report trends, not just counts. Show whether total interest is falling and whether repayment keeps pace with new debt. -->

| Metric | Definition | Last quarter | This quarter | Trend |
|---|---|---|---|---|
| Open items | Count of Open, Planned and In progress | *Example:* 34 | 29 | Improving |
| Total monthly interest | Sum of $I$ over open items | 142 h | 118 h | Improving |
| Items added / closed | New entries versus closures | 9 / 6 | 7 / 12 | Improving |
| Budget used | Hours spent on repayment / hours allocated | 380 / 432 | 410 / 432 | Stable |
| High-risk items open | Count with $R = 3$ | 3 | 1 | Improving |
| [Metric] | [Definition] | [ ] | [ ] | [ ] |

Narrative: [Two or three sentences for leadership on the effect of
repayment.] *Example:* Splitting the shared order database (TD-001)
removed the most frequent release blocker; lead time for order changes
dropped from 6 to 3 days.

## Standard and licence note

Based on common engineering practice for technical debt management. The
technical debt quadrant is a concept by Martin Fowler ("TechnicalDebtQuadrant",
martinfowler.com, 2009), described here in original words. Original text
written for this collection; examples are illustrative. Template licence: MIT.