Agent Wranglers

TKO-24Recommended

Keep a debt register in the repository

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.

By Agent Wranglers. Updated .

How to do it

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. 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 says.

Examples

JavaScript example

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

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]))

How to 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.

For agents: this playbook is free to use under CC 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.