Skip to main content

Technical-Debt Ledger -- Not Everything Gets Fixed

What This Concept Is​

A technical-debt ledger is a written list of known code problems you have decided not to fix right now, with enough context to decide later. Each entry names:

  • the problem, in one sentence;
  • the location in the code;
  • the severity (same scale as triage: Sev-1 through Sev-4);
  • the impact if left alone;
  • why it is deferred, explicitly;
  • the trigger that would cause you to act on it (a condition, not a wish).

The ledger sits in the repo as a markdown file (DEBT.md or similar) and is maintained like any other code artefact. It is the difference between "we know about this" and "we hope we remember this."

This concept sits on top of Ward Cunningham's original technical debt metaphor (adopted code that works against future change) and Martin Fowler's Technical Debt Quadrant (reckless vs prudent, deliberate vs inadvertent). The ledger is how a capstone turns that metaphor into an operational artefact: every entry is, in Fowler's quadrant, a prudent deliberate debt, because you declared it, priced it, and set a trigger.

This is a supporting concept in this cluster because it depends on the judgment developed in the preceding primary concepts (cadence and self-review), but it is indispensable in a real capstone.

Why It Matters Here (In the Capstone)​

In a capstone, most problems you notice cannot be fixed the same day. The question is: where does that knowledge go? Three options:

  • into your head (lost within a week);
  • into the code as a TODO comment (invisible to planning, eventually ignored);
  • into a ledger entry (actionable, inventoried, negotiable).

A ledger lets you separate "we will fix this" from "we will ship with this" from "we will ship and stop pretending we will fix it." It is also the most defensible artefact to produce when explaining to a reviewer or graduator why a decision was made.

Concrete Example(s) -- from a real capstone​

A sample entry:

id:       DEBT-2026-04-10-03
title:    ad-hoc error translation in TaskService
location: task_svc.py:58-102 and three call sites
severity: Sev-3
impact:   every new endpoint reinvents error-shape translation;
          one caller currently leaks a stack trace on validation failure;
          users see inconsistent error messages across endpoints
why-deferred:
          fixing this requires extracting an error middleware, touches three
          files, and adds ~100 lines plus tests. Week 5 is focused on the
          sync feature; this is not blocking delivery.
trigger:  do before the week 7 polish pass, OR immediately if a second
          endpoint starts leaking internal errors, OR if we introduce a
          public error API.
owner:    me
added-by: 24-hour read-through on 2026-04-10
status:   open

Five to fifteen such entries is typical for a well-run capstone. More than 25 suggests the ledger is being used as a dumping ground; fewer than three suggests either denial or genuinely clean code (usually denial).

Common Confusion / Misconceptions​

The most common misconception is that the ledger is a to-do list. It is not. A to-do list implies "we will do all of these." A ledger explicitly accepts that some entries will ship unfixed. Severity and trigger decide which.

A second confusion is using the ledger to log feature requests. The ledger is specifically for structural or quality debt in code you already shipped. Feature work belongs on the product backlog.

A third is writing entries without a trigger. "Do this eventually" is not a trigger. "Do this before public launch" or "Do this when we add a second external provider" is a trigger. Without one, the entry is noise.

A fourth is treating every entry as equivalent. Fowler's quadrant is a better mental model: deliberate prudent ("we knew the cost and chose to ship") is different from inadvertent reckless ("we did not know we were making a mess"), and the fix for each is different -- the first is closed when the trigger fires, the second needs root-cause analysis in your self-review first.

How To Use It (In Your Capstone)​

Maintain the ledger with three habits:

  1. Add. After the 24-hour read-through (Concept 14), anything you noticed but did not fix becomes a ledger entry, or is explicitly declined.
  2. Audit. Once a week, open the ledger. For each entry, decide: still valid, now urgent, or delete (resolved or no longer relevant).
  3. Defend. In any review or checkpoint, be able to explain each live entry: severity, impact, why-deferred, trigger. If you cannot defend one, it should not be there.
  4. Classify. Tag each entry with Fowler's quadrant cell (prudent/reckless Ã-- deliberate/inadvertent) so you can see at a glance which entries came from capacity choices and which came from mistakes.
  5. Close on trigger. When a trigger fires, do the work, link the commit, and close the entry. Do not let it linger as a zombie.
  6. Promote. If an entry has been open for four weeks without a trigger firing, either the trigger was not real or the priority was wrong; promote or delete.
  7. Never TODO. If you catch yourself typing TODO: in code, stop and write a ledger entry instead.

Ledger Audit Protocol​

Once a week, run a structured audit:

  1. Sort by age. Any entry older than four weeks without a trigger firing is either delete, defer harder, or promote to "this week."
  2. Cluster by theme. If three entries describe the same kind of rot (validation, error-handling), that is a signal for a single deeper refactor, not five small ones.
  3. Check triggers. For each entry, is the trigger concrete? Rewrite or delete.
  4. Review severity. Has anything shifted? An ignored Sev-3 can become a Sev-1 after a real incident. Update.
  5. Close the resolved. Any entry whose trigger fired and whose work is done gets closed with a commit link.

An audit should take 20-30 minutes. If it takes more, the ledger has grown beyond what the capstone needs.

Telling a Ledger Story​

At the capstone review, you will be asked: "What did you leave unfixed and why?" The ledger is your answer. A defensible narrative looks like:

"I shipped with 11 open ledger entries. Five are Sev-4 (cosmetic or minor ergonomic); three are Sev-3 with triggers tied to post-release metrics; three are Sev-2 with triggers tied to the next feature that would be affected. No Sev-1 entries are open. Each entry names location, severity, impact, why-deferred, and trigger."

That is a professional answer. "We did not have time" is not. The ledger makes the difference.

Anti-Patterns to Recognize​

  • TODO comments in code. Every TODO is a ledger entry waiting to be written.
  • Wishful trigger. "Trigger: if we have bandwidth."
  • Ledger drift. The ledger and the code no longer line up.
  • One-entry ledger. A single catch-all entry ("refactor everything later").
  • Infinite ledger. Entries accumulate and nothing is ever closed.

See also (integrative)​

External references:

Check Yourself​

  1. What separates a ledger entry from a TODO comment?
  2. Why is a trigger required, not optional?
  3. Why is the ledger not a to-do list?
  4. What does an audit do that individual entry review cannot?
  5. Using Fowler's quadrant, which cell do most of your current ledger entries fall into, and what does that tell you about your team's debt profile?

Mini Drill or Application (Capstone-scoped)​

  1. Create or open DEBT.md in your capstone repo. In one sitting, add at least five live entries using the sample format.
  2. For each entry, write severity, impact, why-deferred, and a trigger that is a condition, not a wish.
  3. Classify each entry with its Fowler quadrant cell. Note which cell dominates.
  4. Audit the list: remove one entry, promote one to "fix this week", and link both to their commits or resolution reasons.
  5. In your capstone review narrative (for M05), draft the three-sentence paragraph that summarises the ledger at shipping time, following the example above.

Source Backbone​

Capstone implementation applies earlier code-quality, testing, and refactoring material. These books are the source backbone for that practice.