What is a Debt Ledger?
Debt Ledger: A living document (usually a DEBT.md file in the repository) used to track Synthetic Debt. It turns unconscious, invisible accumulation into a conscious management process by recording exactly what debt was taken and why.
Why You Need a Ledger
Synthetic debt is invisible during the "Honeymoon" phase of development. Because the code "works," teams assume it has zero cost. A Debt Ledger makes the cost explicit before it reaches critical mass.
Anatomy of a Ledger Entry
Every item in a Clean Vibe Debt Ledger includes:
- Category: Which of the 7 synthetic debt categories (ARCH, KNOW, SEC, etc.)?
- Description: What exactly is the shortcut or "black box"?
- Rationale: Why was this debt taken? (e.g., "Speed for Investor Demo").
- Severity (Debt Units): How dangerous is this? (1 = Low, 10 = Critical).
- Payback Plan: How will we fix it?
- Deadline: When is the point of no return?
Example Entry
### [ARCH-042] Task Sorting Logic
- **Date:** 2026-01-11
- **Debt Category:** 🏗️ Architectural / 🧠 Knowledge
- **Severity:** 5 Units (High)
- **Description:** AI generated a 300-line sorting algorithm we don't fully understand.
"Magic Black Box" smell detected.
- **Rationale:** Needed working demo by 2 PM for sprint review.
- **Payback Plan:** Senior dev to refactor using standard library and add ADR.
- **Deadline:** End of Sprint 4.
The Debt Formula
Σ(Sev × Count)
The Debt Formula
100 Units
Threshold for Project Crisis
Source: Ch 10
The ledger allows you to calculate your Total Debt Load. In Clean Vibe Code, we show that once a project exceeds 100 Debt Units, the cost of maintenance begins to exceed the value of new features.
Managing the Ledger
- Morning Review: Check the ledger before starting work.
- Debt Sprints: Dedicate 20% of your time to paying down items in the ledger.
- Conscious Choice: If you can't afford to record it in the ledger, you can't afford the debt.
Related Terms
- Synthetic Debt: The thing you are tracking.
- Debt Unit: The measure of severity.
- Living With Debt: The chapter on long-term management.
Book Reference
The Debt Ledger is used throughout the TaskFlow case study:
- Chapters 1-12: Watch the ledger grow to 982 units of disaster.
- Chapter 17: Living With Debt — the official framework for ledger management.
- Appendix D: Templates for your own ledger.