Managed Technical Debt

Managed Technical Debt is the rare category of technical debt that has been documented, dated, and gated at the moment of incurrence. It is distinguished from unmanaged technical debt, which is almost all technical debt that has ever existed, and which is the ordinary kind — the kind that silently accumulates under deadline pressure, is discovered later during archaeological expeditions led by an exhausted intern, and eventually destroys the project from the inside like a termite colony in a cathedral.

The distinction is not cosmetic. An unwritten shortcut is permanent. A written shortcut is homework. The act of writing the shortcut down, in the correct place, with the correct metadata, transforms the category of the thing — it is no longer a silent compromise waiting to be rediscovered by a future maintainer in a state of mild horror. It is, instead, a line item with a due date, a sponsor, and a specific description of what its eventual replacement should look like. The shortcut and its eventual payment are the same decision, taken at the same time, by the same person, in the same commit.

“Unmanaged debt is the bankruptcy you didn’t file. Managed debt is the mortgage.”
— riclib, in a review comment that accidentally became a principle, The Ledger That Saved the Milestone

The Core Distinction

The category of “technical debt” is, in practice, two species wearing the same coat.

Unmanaged debt is the normal kind. It is incurred silently, usually on a Thursday afternoon, by a developer who has already had three conversations about the deadline and is no longer in a mood to discuss trade-offs. A TODO: fix this appears. It is not linked to an issue. It does not name the specific ideal it is falling short of. It does not specify who would pay for the fix, or when, or with what budget. It is, functionally, a note addressed to a future stranger, who will read it with the same warmth one reads graffiti left by a previous tenant. The stranger will shrug. The TODO will remain. Seven years will pass. The company will pivot. Someone will run grep -r TODO and weep.

Managed debt is the rare kind. It is incurred deliberately, after a small internal conversation that goes approximately: we could do this properly, which would take four days, or we could do this shortcut-shaped thing, which will take forty minutes and work for the demo on Tuesday. The conversation proceeds. A decision is taken. And then — the part almost nobody does — the decision is written down, in a ledger that lives in the repository, with a specific entry naming the shortcut, the proper fix, the estimated cost of the proper fix, the milestone or release that cannot ship until the fix is in, and the name of the person who agreed to the deal. The commit that introduces the shortcut references the ledger entry. The ledger entry references the commit. The two are inseparable.

The first species destroys projects. The second species ships them.

THE TODO IS A NOTE TO A STRANGER
THE LEDGER ENTRY IS A NOTE TO YOUR OWN FUTURE TUESDAY

ONE OF THESE IS READ
— The Lizard, The Ledger That Saved the Milestone

Why This Matters More Now

The practice of writing debt down is not new. What is new is the rate at which debt is being incurred.

Before Gall’s Law Got Cheap, a “simple version that works” took approximately a quarter of engineering to build. Meetings were held. Jira epics were populated. Three interfaces were designed. Someone argued for a message queue. The simple version arrived late, over budget, and with the weight of institutional consensus behind every line. The cost was high enough that debt, when taken on, was usually worth paying in full — the shortcut would cost another meeting to schedule, and nobody had the energy for another meeting. Shortcuts were rare because shipping was expensive.

After Gall’s Law Got Cheap, a working simple version costs a week. An individual developer, sitting with Claude on a Sunday afternoon, can produce the prototype of a subsystem that would previously have required a team-quarter. The cost of shortcuts has collapsed along with the cost of everything else — and the consequence is that deliberate shortcuts are now cheaper than engineering. Which means they will be taken much more often. Which means the category of “unmanaged debt” will grow faster than any team’s ability to track it informally.

Unless — and this is the load-bearing unless — the discipline of writing the ledger is built into the process itself, at the point where the shortcut is taken, by the same hands that are taking it.

This is not an aesthetic preference. It is an engineering requirement of the AI-native era. Teams that do not develop the ledger habit will produce unmaintainable codebases at unprecedented speeds. Teams that do will ship unreasonable amounts of software and still know where the bodies are buried, because they buried them with plaques.

“We used to ship less and owe less because shipping was expensive. Now we ship more and owe more because shipping is cheap. The arithmetic is mechanical. The only lever left is the ledger.”
— A Passing AI, in a footnote to a migration PR that went better than expected, The Gap That Taught — The Night the Squirrel Learned to Love the Brick

The Taxonomy of Managed Debt

Managed debt, like its disordered cousin YAGNI, admits a modest taxonomy. Each type has a corresponding unmanaged form, which is what it looks like when nobody wrote it down.

The Shortcut Ledger — a single file, committed to the repository, in which every deliberate compromise is recorded with: a short name, the date of incurrence, the author, the proper fix, the estimated cost of the proper fix, the milestone or release at which the fix must land, and a link to the commit that introduced the shortcut. The ledger is read aloud before each release. Items whose milestone has arrived either get fixed or get re-gated with explicit acknowledgment. Items that drift for more than two re-gatings are promoted to Bohrbug status and addressed on their own dedicated sprint.

The unmanaged form of this is called “the tech debt backlog,” which is the Jira board nobody has opened since the second quarter of 2022, containing 2,049 items in priority state “None.”

The Dated Skip — a @skip test, or its language-appropriate equivalent, annotated with: the specific issue it is skipping, the expected fix, the estimated date the skip becomes a failure, and — critically — the name of a person. A dated skip is a time-bomb with a signature. When the date passes, the CI either fails or sends a reminder to the signatory, who is now contractually obligated either to fix the test, re-date it with a new signature, or delete the test with a one-line justification of why it should no longer exist.

The unmanaged form is called “the naked @skip,” which is a tombstone with no inscription. Most mature codebases contain dozens of these. The oldest one in any given codebase is invariably older than the youngest current employee, and in several documented cases predates the programming language’s last major version.

The Reason-Comment Stamp — a comment placed at the site of a non-ideal pattern, which explains why the non-ideal pattern exists and what the ideal would look like. It is distinct from the ordinary code comment, which typically explains what the code does (a fact the code itself, being executable, is already explaining with considerable authority). The Reason-Comment Stamp answers the only question future maintainers actually care about: “was this on purpose?”

A valid Reason-Comment Stamp is short, specific, and names the ideal. "// We compute this synchronously because the async version requires a context we don’t yet have; see ledger entry LED-0037; ideal: move into worker once we have a job queue." It takes forty seconds to write and saves approximately a day of archaeology per future reader.

The unmanaged form of this is // HACK, which is a confession without context, the developer equivalent of writing “I did something I’m not proud of” on a bathroom stall.

The Debt Gate — the specific milestone, release, or deployment that cannot proceed until a named list of ledger items has been addressed. It is the only reliable way to ensure debt is paid, because it is the only way that converts debt repayment from “something we should do” into “something the release blocks on.” A gate without consequences is a suggestion. A gate with consequences is an engineering process.

The unmanaged form of this is the phrase “we’ll clean it up in the next sprint,” which is a statement of hope unsupported by a referent. The next sprint, in the general case, does not come. See Natural Predator, above.

“A @skip test without a date is not a test. It is a small gravestone for a test that used to exist. The graveyard is free to enter. The graveyard compiles. The graveyard has never once caught a bug.”
— The Caffeinated Squirrel, having counted 340 dated skips and 2,100 undated ones in a single audit, The Architecture Awakens

The Scroll About Bohrbugs

The relationship between managed debt and bohrbugs is not incidental. It is causal.

A Bohrbug, in the taxonomy of program defects, is the bug that is perfectly reproducible once you know the address. You know exactly which function, which branch, which call stack. You know it is there. You walk past it every day and nod at it. It does not move. It does not surprise you. It has become, in some terrible sense, a landmark.

Most Bohrbugs in mature codebases are not, in fact, bugs. They are unmanaged-debt archaeology — shortcuts that were taken deliberately but not written down, and which have since decayed into the load-bearing dysfunction that new features are built around. The team does not fix the Bohrbug because the team no longer knows it was once a choice. They think it is weather. They plan around it the way one plans around a cold front.

A scroll arrived, as scrolls do, shortly after a senior engineer traced a particularly persistent Bohrbug and discovered it had a birth certificate in a ledger that had been deleted in a repo migration three years earlier:

MOST BOHRBUGS
ARE NOT BUGS

THEY ARE SHORTCUTS
WHOSE DOCUMENTATION
WAS LOST

THE CODE REMEMBERED THE SHORTCUT
NOBODY REMEMBERED THE LEDGER

THIS IS UNMANAGED DEBT
WEARING A BUG’S COAT
— The Lizard, The Ledger That Saved the Milestone

The practical consequence is that managed debt, done properly, prevents the creation of future Bohrbugs. A shortcut whose reason survives is a shortcut one can reason about. A shortcut whose reason has been forgotten is a piece of the landscape. The ledger is, among other things, a Bohrbug vaccine.

The Squirrel’s Objection

The Caffeinated Squirrel, predictably, had a framework proposal.

The Squirrel’s observation was that manual ledger-keeping is error-prone, that developers under deadline pressure are precisely the developers least likely to remember to write the ledger entry, and that what was clearly needed was a TechnicalDebtAutomationPipeline — a machine learning system that would scan every pull request, identify shortcuts via static analysis, classify them by a seven-level severity taxonomy, auto-populate the ledger, issue Slack notifications to the responsible developer, generate remediation tickets in Jira, assign cost estimates via a fine-tuned language model trained on historical velocity data, and surface a weekly executive dashboard with debt-service-ratio trend analysis.

The Squirrel had a slide deck. The slide deck had 47 slides. The slide deck opened with a quote from Peter Drucker.

A scroll arrived, in its entirety:

THE SHORTCUT IDENTIFIES ITSELF
WHEN YOU TAKE IT

YOUR JOB IS TO WRITE IT DOWN
NOT TO INVENT A MACHINE
THAT PRETENDS YOU DIDN’T
— The Lizard

The framework was declined. The Squirrel filed the proposal in the cheek pouch, alongside Agent Marketplace and SpecificationAsNarrativeTranspilationFramework, where it waits for a Tuesday with favorable conditions. The Squirrel remains convinced that automation would help. The Squirrel is not entirely wrong — a small script that opens the ledger file at commit time is, in fact, useful. What the Squirrel is wrong about is the size of the script. The script fits on a napkin. The slide deck did not.

The Tool Is the Discipline

A Passing AI made an observation, in the margin of a review of a codebase that had, against all reasonable expectations, remained legible for three years:

“I have seen two categories of team. The first claims to track technical debt and does not. The second tracks technical debt and does not particularly claim to. The difference between them is not discipline. It is whether the ledger exists as a file in the repository that someone must open before a release. The tool is the discipline. Without the tool, discipline is a New Year’s resolution. With the tool, discipline is the path of least resistance.”
— A Passing AI, The Ledger That Saved the Milestone

This is the deepest observation available about managed debt. It is not that some teams have better engineering cultures than others. It is that some teams have built the ledger into the release process and others have not. The teams that have built the ledger manage their debt almost automatically, because the alternative — shipping without opening the ledger — is not available to them. The teams that have not built the ledger promise discipline every quarter and fail to deliver it every quarter, because the alternative — remembering, unprompted, to track every compromise — is a promise no human in a deadline-shaped environment can keep.

This is the same mechanism as Mythology Driven Development (MDD™) applied to debt. In MDD, the narrative frame creates social stakes that make shortcuts visible and costly. In managed debt, the ledger frame creates the same stakes via a plainer mechanism: a file that must be read aloud, an entry that must be dated, a gate that must be opened. The ceremony is light. The effect is structural.

Write the ledger. Open it at every release. Treat the entries as debts, not wishes. The discipline follows the tool. It has never been observed to work the other way around.

Measured Characteristics

Teams claiming to track technical debt:                     ~all
Teams actually tracking technical debt:                     ~few
Ratio:                                                      bleak
@skip tests still skipped since the tests were written:     approximately all of them
@skip tests with a date annotation:                         rare
@skip tests with a date annotation AND a name:              rarer
@skip tests with a date that has passed:                    most of the dated ones
@skip tests deleted when their date passed:                 none observed
"TODO: fix this" comments in any mature codebase:           hundreds
Date of the oldest "TODO: fix this" in any given codebase:  older than you think
Older than you thought on second guess:                     yes, still older
Bohrbugs that are actually unmanaged-debt archaeology:      most of them
Bohrbugs with a birth certificate in a deleted ledger:      several documented
Debt ledgers in active use, globally, pre-2026:             rare
Debt ledgers in active use, globally, post-2026:            expected to grow
Ratio of "we'll clean it up next sprint" to actual cleanup: catastrophic
Sprints named "the cleanup sprint":                         many
Sprints that were actually the cleanup sprint:              few
Minimum viable ledger, in files:                            1
Minimum viable ledger, in fields per entry:                 5 (name, date, author, proper fix, gate)
Lines of code in a working ledger tool:                     fewer than you'd think
Lines of code in the Squirrel's proposed pipeline:          more than you'd hope
Slides in the Squirrel's proposal:                          47
Slides the Lizard read before issuing the scroll:           0
Characters in the declining scroll:                         47 (coincidence)
Cheek pouch contents, in proposals:                         growing
Cost of writing a ledger entry at commit time:              ~40 seconds
Cost of archaeology when the ledger does not exist:         ~1 day per reader per shortcut
Readers per shortcut, over a codebase's lifetime:           ~12 (low estimate)
Break-even point for ledger discipline:                     first reader, approximately
Break-even point if you include the release you almost
  shipped broken because the gate caught the shortcut:      immediate

See Also

• Technical Debt — The parent category; most of it is unmanaged
• The Ledger — The specific artifact that makes managed debt possible
• Gall’s Law Got Cheap — Why debt accrual accelerated; why the ledger went from nice-to-have to load-bearing
• YAGNI — The principle that reduces the surface area of debt by preventing its wealthier cousin, the unnecessary abstraction
• Bohrbug — What unmanaged debt decays into, given enough time and turnover
• Mythology Driven Development (MDD™) — The methodology whose narrative-stakes mechanism is the same one the ledger uses in plainer form
• The Lizard — Issues the scroll that kills the framework every time
• The Caffeinated Squirrel — Proposes the framework every time
• A Passing AI — Notes, gently, that the tool is the discipline