# Technical Debt Audit Turns a codebase into a register of what it costs to keep — ordered by the work each item blocks, not by how it looks. ## Deliverable One Markdown document, `technical-debt-register.md`, in the structure set out under **Output** below. It feeds planning directly: the ordered register is a list of items that can be sequenced against other work. ## Required inputs - **Access to the codebase, or documentation that describes it** — enough to locate an item in a file or a module rather than in an impression. - **What the team intends to build next** — the work the debt is measured against. Debt is only debt relative to a change someone wants to make. Without the second, the output is a list of things somebody dislikes. Without either, stop and report it: an audit with no material and no direction produces opinions with headings on them. ## Optional inputs - The change history: what is modified most, and what keeps being modified together - Incident and defect records, and the areas of the system they point at - Test coverage, and the parts of the system the tests do not reach - Build and release records, and where they fail or wait - The team's own account of what slows them down, attributed to the person who said it - Earlier audits of the same system, and what was done about their findings An absent source narrows the audit; it never widens the guessing. An item with no observable cost is recorded with its cost `unknown`, never with a cost that merely sounds plausible. ## Execution **1 — Bound the audit.** State what was examined and what was not: which parts of the system, which records, which period of history. An audit that does not state its boundary is read as complete, and the areas nobody looked at are read as clean. **2 — Collect candidates from evidence, not from taste.** Every candidate needs an observation behind it: a failure, a change that had to be repeated in several places, an area the tests do not reach, a workaround someone described. Code that is merely unfamiliar or unfashionable is not a candidate and does not enter the register. **3 — Locate each item exactly.** The file or the module, and the boundary of the item inside it. An item located at the level of a whole layer cannot be scheduled, cannot be argued about, and cannot be verified as fixed. Where the location is genuinely diffuse, say so and name the boundary that contains it. **4 — State the cost now, in observable terms.** What does this item make someone do today: the manual step before a release, the change repeated in several places, the failure that recurs, the review that takes a second person. Where no cost can be observed, write `cost unknown` rather than converting an impression into a figure. **5 — State the interest.** What the item charges on nearby work: which changes it makes slower, which changes it makes risky, and which changes it prevents outright. This is the section that separates debt from an imperfection, and an item that charges nothing on anything belongs in the accepted list. **6 — Size the remediation and its risk.** What the fix is, what it touches, what it would take in the team's own unit of sizing if they supplied one, and what could break while it is done — including the work that must pause around it. Where the team supplied no sizing, record `unsized` and name who can size it. **7 — Order by what is blocked, and mark what is accepted.** Rank the register by the work each item blocks, taken from the intended work supplied as input, and name that work against each item. An item that blocks nothing and costs nothing is recorded `accepted` with the reason — neither scheduled nor deleted. ## Output `technical-debt-register.md`, in this order: - **1. Input and date** — what was examined, what was not, which intended work the register is measured against, and when - **2. Register** — per item: what it is, where it is, the evidence behind it, and its cost now - **3. Interest** — per item: the work it slows, the work it makes risky, and the work it prevents - **4. Remediation** — per item: the fix, what it touches, its size or `unsized`, and the risk of doing it - **5. Order** — the items ranked by the work they block, with that work named against each - **6. Accepted** — items that cost nothing and block nothing, each with the reason it is accepted - **7. Unverified** — items reported by a person and not confirmed against the system - **8. Open questions** — the question, what it blocks, who can answer it ## Validation The register is ready when all of these hold: - Every item in section 2 names a file or a module and the evidence behind it - Every item in section 2 carries an observable cost or the marker `cost unknown` - Every item in section 3 names at least one piece of work it affects, or moves to section 6 - Every item in section 4 states the risk of the remediation, not only the remediation - Section 5 is ordered by blocked work, and names the blocked work against each item - No size, count or proportion appears that the team did not supply Fail the run if an item appears with no evidence behind it, or if the register is ordered by anything other than the work each item blocks. ## Failure handling - **No access to the codebase** — audit the documentation supplied, place every item in section 7 as unverified, and state that a register built from documentation records what was written down rather than what is there. - **No statement of intended work** — produce sections 1 to 4, 7 and 8, leave section 5 unordered, and report that without intended work every ordering is a matter of taste. - **The team supplied no sizing** — record every remediation `unsized`, name who must size it, and deliver the register without a size column rather than with an invented one. - **A finding is disputed by the team** — keep the item, record the evidence and the dispute side by side with both names, and raise it in section 8. Do not remove an observed finding because it is unwelcome. - **Partial access** — audit what was reachable, name in section 1 exactly what was not, and deliver. An audit of part of a system is useful when it says which part.