technical_debt_management v1.0.0

name: technical_debt_management description: "Make technical debt visible and decidable: inventory debt items in a register with priced principal and interest, separate real debt from bugs, features, and untouched mess, estimate interest from real changes, rank repayment by payback and risk, and write the one-page business case. Use when a team says delivery is slowing down, argues about refactoring, inherits a messy system, plans a cleanup, or needs to justify debt work to non-engineers."

Technical Debt Management

Purpose

Technical debt is a metaphor Ward Cunningham coined in 1992 to explain refactoring to non-technical stakeholders. The debt is internal quality that was traded away, deliberately or by learning later. The principal is the effort to fix it properly. The interest is the extra effort every later change costs until it is fixed. Martin Fowler's example sets the scale: a feature that would take 4 days in a clear module structure takes 6 days in a confusing one, so 2 days is interest on that change, and the 5 days it would take to clean the structure up is principal.

Most debt arguments fail before they start, for three reasons this skill is built against. First, debt, bugs, missing features, and personal style complaints get lumped into one pile, so nothing in the pile is decidable. Second, nobody prices the interest, so the loudest complaint wins instead of the most expensive problem. Third, the fix gets pitched in engineering words to people who fund work in days and risk. The register, the interest worksheet, and the quarterly review in this skill turn debt from a feeling into a short list of priced items with a decision on each one.

Debt is not automatically bad. Deliberate, priced debt taken to ship something sooner is a normal business decision. Debt causes damage when it is hidden, when nobody knows what it costs per quarter, and when repayment is never decided either way.

Workflow

1. Run an inventory sweep and collect candidate items from evidence, not opinion.

• Static analysis output and known deferred defects from the tracker.
• Change history: which areas get touched most, and which changes took far longer than similar changes elsewhere.
• Incident reviews that name the same area more than once.
• A short team survey in the style Google uses for perceived debt: how much debt slowed you down this quarter, where the worst friction sits, how much was taken on deliberately, and how much was invested in paying it down. Google's own research tested 117 candidate log metrics against engineer surveys and found no single metric predicted perceived debt reliably, so pair any metric with the survey instead of trusting one number.
• TODO and workaround comments, counted by area, as leads to check rather than proof.

1. Filter the candidates with the debt test in references/register-fields.md. A candidate becomes a register item only if it passes all four checks.

• It has a location narrow enough to point at.
• It costs something measurable now: extra time on changes, recurring incident or manual cost, or a named risk.
• A fix exists whose effort can be estimated as principal.
• It is not already a normal bug fix, a wanted feature, or a style preference. Deferred known bugs count as defect debt only when the team knowingly pushes the fix past the normal cycle and accepts the cost.

1. Classify each item twice.

• By artifact type, following the taxonomy from Kruchten, Nord and Ozkaya: code, architecture, test, documentation, infrastructure, requirements, defect, or build.
• By Fowler's quadrant, which crosses how the debt was acquired (deliberate or inadvertent) with how it was judged (prudent or reckless).
• Deliberate and prudent: a shortcut taken on the record to ship sooner, with the cost weighed. A bill coming due, handled as a decision.
• Deliberate and reckless: a known shortcut taken with no weighing and no plan. Fix the habit that produced it as well as the item.
• Inadvertent and prudent: the team built the best design it understood, then learned better. Fowler notes this is Cunningham's original case, and it happens to good teams.
• Inadvertent and reckless: the team did not know what good looked like. That is a skills and review gap. Register the cost, and treat the cause separately.

1. Price every item with references/interest-worksheet.md.

• Interest per touch comes from the last 3 to 5 real changes in the area: actual days minus the days the same change would have taken in a clean version of that area.
• Touches per quarter comes from change history, counted, not guessed where counting is possible.
• Recurring interest covers costs paid without any change: incident time, manual steps, slow pipelines.
• Principal covers the full fix: the change, tests, migration, rollout, and documentation.
• Label every number an estimate and keep the range. Fowler warns that none of these costs are objectively measurable and that estimate accuracy is low. Comparable and honest beats precise and invented.

1. Record the items in the register and run the tool.

python3 bin/debt_register.py assets/register.csv --development-days 400

The tool validates the register, computes quarterly and annual interest per item, computes payback in quarters as principal divided by quarterly interest, ranks items, and totals the portfolio. Field rules are in references/register-fields.md. A register that fails validation gets fixed before any review sees it.

1. Read the portfolio number alongside the item list. The tool can also report the technical debt ratio from the SQALE method, remediation cost divided by development cost, when a development cost figure is supplied. SonarQube ships a rating grid for that ratio: A at or below 5%, B above 5% to 10%, C above 10% to 20%, D above 20% to 50%, E above 50%. Present that grid as Sonar's grid for static analysis findings, not as a universal standard, and remember it only sees what a scanner can see. Test gaps, missing documentation, and manual process debt need register rows of their own.

1. Hold the prioritisation review and decide every item, using references/prioritisation-review.md.

• Critical risk decides first, ahead of payback math: a security hole, a data loss path, or one person holding a critical manual process.
• Then rank by payback. An item whose principal is smaller than one quarter of its interest should rarely wait.
• An item with zero quarterly interest gets Monitor or Accept, however ugly it looks. Interest is paid on touch. Fowler's point is direct: a terrible area nobody has to modify is not currently costing anything, while cruft in a high-activity area charges interest on every change.
• Each item leaves with one of five decisions: pay now, pay gradually, schedule for a named quarter, accept on the record with a review date, or retire with the system it lives in.

1. Fund repayment as a stated amount, and pay large principals gradually where that fits. State the repayment capacity for the quarter in days, name which items it covers, and record who decided the amount. No primary source sets a standard share of sprint capacity for debt work, so this skill does not invent one. For gradual payment, take a slice of the principal inside changes that touch the area anyway, so cleanup effort lands where interest is actually being charged.

1. Gate new deliberate debt at the moment it is taken on. A deliberate shortcut is allowed when the decision is recorded the same day as a register row with an owner, a priced estimate, and a review date. A shortcut with no row is how reckless debt starts. Reckless and inadvertent items get a cause note, since paying the principal without changing the habit just refills the register.

1. Re-price quarterly. Touches move, so interest moves. An area a new project is about to land on can double its interest with no code change at all. Retire rows when the fix ships or the area is deleted, and keep the paid rows in the file with status paid so the next review can see what repayment bought.

Worked example

assets/register.csv holds six priced items. Running it with a 400 day development cost gives:

P0 D-004 principal 6d interest 5d/qtr payback 1.2q No regression tests on refund path P1 D-001 principal 5d interest 6d/qtr payback 0.83q Confusing checkout module structure forces slow feature work P2 D-002 principal 10d interest 4d/qtr payback 2.5q Payment provider calls scattered with no single adapter P2 D-005 principal 8d interest 3d/qtr payback 2.67q Manual deploy steps known by one person P2 D-006 principal 2d interest 0.5d/qtr payback 4.0q Onboarding docs describe the old auth flow Monitor D-003 principal 20d interest 0d/qtr payback never (no interest) Legacy report generator nobody changes TOTAL principal 51d interest 18.5d/qtr (74d/year) across 6 open item(s) DEBT RATIO 12.75% Sonar grid band C (remediation / development cost)

Read it the way the review in references/prioritisation-review.md does. D-004 ranks first on critical risk, not math. D-001 pays back in under a quarter, so waiting a quarter costs more than fixing it. D-003 carries the biggest principal in the register and zero interest, because nothing touches it and it causes no recurring cost, so the correct decision is to accept and monitor it. The portfolio pitch writes itself from the totals: paying D-004 and D-001 costs 11 days and removes 44 days of interest a year.

assets/register_bad.csv is the same register shape with a bad type, a bad quadrant, a duplicate id, a missing owner, and a non-numeric principal. The tool reports 7 errors and fails, which is the correct result for both files.

Output Contract

A finished debt management pass delivers:

• A validated register CSV with one row per item, every field in references/register-fields.md filled, and the tool output showing zero errors.
• A price per item: principal, interest per touch, touches per quarter, recurring interest, quarterly and annual interest, and payback in quarters, each labelled as an estimate with its evidence noted.
• A portfolio summary: total principal, total interest per quarter and per year, the top item's share of total interest, and the debt ratio with its basis stated when one is reported.
• A decision per item from the five options, with status and review date updated in the register, and the funded items named against a stated repayment capacity in days.
• For any item needing funding beyond the team's own capacity, a one-page business case in the format in references/prioritisation-review.md: the item in plain words, the interest, the principal, the payback, and the cost of waiting one more quarter.
• A separation note listing what was filtered out of the register and why: bugs routed to the bug queue, features routed to the roadmap, and untouched mess left unregistered.

Report numbers as the tool computed them and estimates as estimates. Report a decision as made only when a named owner made it.

Operating Rules

1. No price, no priority. An item with no interest estimate is an opinion and stays off the ranked list until the worksheet prices it.
2. Never rank by ugliness, age, or complaint volume. Rank by risk first, then by payback, and let zero-interest items sit.
3. Never present the Sonar rating grid, or any single metric, as the whole debt picture. Scanner findings miss test, documentation, and process debt, and Google's metric research is the standing warning against single-number confidence.
4. Never invent a standard allocation for repayment capacity. State the amount a team actually chose, in days, with the decider named.
5. Deliberate debt without a register row, an owner, and a review date is reckless debt in progress. Record it the day it is taken on or do not take it.
6. Accept is a real decision and needs authority behind it. An item nobody with authority has seen is open, not accepted.
7. Paying principal does not close the cause. Reckless and inadvertent items need the habit, review gap, or skills gap named, or the register refills.
8. Keep estimates honest in both directions. Inflated interest to win funding destroys the register's credibility at the first re-price, and understated principal does the same at the first overrun.
9. Retire debt by retiring or fixing the area, never by deleting the row. Paid and retired rows stay in the register as the record of what repayment bought.