---
title: "Keep a debt register in the repository · Agent Wranglers"
url: https://agentwranglers.se/playbook/codebase-takeover/technical-debt/debt-register
id: TKO-24
level: Recommended
updated: 2026-10-22
tokens: 1033
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Keep a debt register in the repository

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Technical debt](https://agentwranglers.se/playbook/codebase-takeover/technical-debt.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: TKO-24
- Level: Recommended
- Chapter: [Technical debt](https://agentwranglers.se/playbook/codebase-takeover/technical-debt.md)
- Rule: Record each piece of technical debt in one file in the repository. Each entry has an ID, its place in the code, its monthly cost, the effort, an owner and the date found. Rank it by cost divided by effort.
- Check: A script fails the build when a register entry lacks any of the six fields. It also fails on a TODO or FIXME that links neither an entry nor a ticket.
- How: Debt that lives in people's heads leaves with them, and debt in a ticket tool loses its link to the code. State the cost in terms the business can weigh, such as hours lost per month, incidents per quarter or a risk from the [risk register](https://agentwranglers.se/playbook/compliance/controls-and-evidence/risk-register.md). Effort is a range in days. Work the top of the ranking first. Every TODO in the code links to an entry or a ticket, as [Link every TODO to a ticket](https://agentwranglers.se/playbook/architecture/comments/todos-with-tickets.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
import { readFileSync } from 'node:fs';

const FIELDS = ['id', 'where', 'costPerMonth', 'effortDays', 'owner', 'found'];
const debt = JSON.parse(readFileSync('docs/debt.json', 'utf8'));
const incomplete = debt.filter(item => FIELDS.some(field => item[field] === undefined || item[field] === ''));
if (incomplete.length) { console.error(`Incomplete: ${incomplete.map(item => item.id).join(', ')}`); process.exit(1); }
const ranked = debt.toSorted((a, b) => b.costPerMonth / b.effortDays - a.costPerMonth / a.effortDays);
console.log(ranked.slice(0, 3).map(item => item.id).join(', '));
```

### Python example

```python
import json, sys

FIELDS = ["id", "where", "costPerMonth", "effortDays", "owner", "found"]
debt = json.load(open("docs/debt.json"))
incomplete = [item["id"] for item in debt if any(item.get(field) in (None, "") for field in FIELDS)]
if incomplete:
    sys.exit(f"Incomplete: {', '.join(incomplete)}")
ranked = sorted(debt, key=lambda item: item["costPerMonth"] / item["effortDays"], reverse=True)
print(", ".join(item["id"] for item in ranked[:3]))
```

## Related rules

- TKO-7 [Fix in risk order](https://agentwranglers.se/playbook/codebase-takeover/triage/fix-in-risk-order.md) in Codebase takeover
- CMP-39 [Keep a risk register with treatment dates](https://agentwranglers.se/playbook/compliance/controls-and-evidence/risk-register.md) in Compliance and governance
- ARC-25 [Link every TODO to a ticket](https://agentwranglers.se/playbook/architecture/comments/todos-with-tickets.md) in Clean code and architecture
- TKO-25 [Spend a set share of each cycle on debt](https://agentwranglers.se/playbook/codebase-takeover/technical-debt/debt-budget.md) in Codebase takeover
- TKO-35 [List what must be rebuilt to grow](https://agentwranglers.se/playbook/codebase-takeover/due-diligence/rebuild-list.md) in Codebase takeover

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/codebase-takeover/technical-debt/debt-register">Agent Wranglers codebase takeover playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Spend a set share of each cycle on debt](https://agentwranglers.se/playbook/codebase-takeover/technical-debt/debt-budget.md)
- [Technical debt](https://agentwranglers.se/playbook/codebase-takeover/technical-debt.md)