DEV Community: Erdi BAY

I Went Looking for the Diff Debt in My Own Repo

Erdi BAY — Tue, 21 Jul 2026 09:40:21 +0000

Two posts ago I said I'd shipped code I never read. It's easy to write that as a general observation about the industry. It's less comfortable to go open your own repo and count.

So I did. Here's what I found, and what I've actually done about it.

The repo

It's a desktop app I built for my own company. Roughly fourteen thousand lines of Python, a Tkinter UI, invoicing and documents and reports, the kind of internal tool nobody else will ever see. I had never written Python before I started it. I built it anyway, with a lot of AI help, learning as I went.

That combination - no prior experience, heavy AI assistance, a real deadline because the business actually needed the thing - is basically a diff debt factory. I wasn't cutting corners on purpose. I just didn't have the knowledge to evaluate half of what I was merging, and it worked, so I moved on.

What I actually found

The clearest example took me months to notice.

Five different parts of the app generate PDFs. Quotes, proformas, reports, petitions, heat treatment certificates. Every one of them was failing, in different ways, at different times, and I kept fixing them individually. Different error, different module, different patch.

The actual cause was one thing: LibreOffice wasn't installed on the machine. Every one of those modules quietly depended on it to do the document conversion. Not one of them said so anywhere. I'd merged that dependency five separate times without ever registering that I'd taken it on.

That's diff debt in its purest form. The code wasn't messy. It wasn't badly written. It just made an assumption I'd never read, and I paid interest on it five times over before I understood the principal.

There were smaller ones too. A path handling bug that only showed up because my Windows username has a Turkish character in it - the code assumed ASCII and nobody, including me, had thought about it. Two Python versions installed side by side, quietly fighting. A stray quotation mark in my system PATH that broke things in ways that looked like code problems for days.

None of these were hard bugs. They were just bugs in code I'd never actually read.

What I do now

I want to be honest about this part, because the tidy answer would be "I went back and reviewed everything." I didn't. Fourteen thousand lines I mostly didn't write is not a realistic weekend project, and pretending otherwise would just be a different kind of lie.

What I do instead:

I audit on failure. When something breaks, that module gets its first real read. Not a patch - an actual sit-down-and-understand-it pass. It's reactive, and it means I'm paying interest before principal, but it's the only version of this I'll actually stick to.

I write down what I learn, right then. The LibreOffice thing is in the README now. Obvious in hindsight, but the whole problem was that it lived nowhere except in code nobody had read. If a module gets its first real read, that read has to leave something behind or I'll be doing it again in six months.

I stopped merging things I can't explain. This is the only genuinely preventive one, and it's the one that matters. If I can't say out loud why a change is correct, it doesn't go in. Not "the tests pass." Not "it looks right." Why it's correct. Sometimes that means asking the model to explain itself and then checking whether the explanation actually holds. Sometimes it means I sit there for twenty minutes on a diff I could have merged in one.

That last one feels slow. It is slow. But it's slow in the same way that reading a contract before signing it is slow.

The part I got wrong

For a long time I thought the problem was AI writing bad code. That's not it. Most of what I merged was fine. Some of it was better than what I'd have written myself at the time.

The problem was that the code entered my repo without ever entering my head. Quality had nothing to do with it. A perfectly good module I don't understand is still a module I can't debug, can't extend, and can't hand to anyone else.

I'm not going to pretend I've paid this off. I've got a repo with thousands of lines in it that I'd struggle to walk you through, and I'm going to be finding out about them one incident at a time for a while yet.

But at least now I know I'm carrying it. That's the difference between debt and a surprise.

Technical Debt vs Diff Debt, and Why I Stopped Treating Them as the Same Thing

Erdi BAY — Thu, 16 Jul 2026 10:16:58 +0000

I started using the term diff debt a couple of weeks ago, and the first reaction I got was pretty consistent: "isn't that just technical debt?"

It isn't. And honestly, the gap between the two is the entire reason I needed a new word for it.

Technical debt, the version we already know

Ward Cunningham gave us the technical debt metaphor back in the early 90s, and it stuck because it's accurate. You ship something quick and messy to hit a deadline, and you pay interest on it later, every time you have to work around the shortcut you took.

The part that never gets said out loud is that technical debt assumes you understood what you shipped. You picked the hacky solution over the clean one on purpose. You could open that file right now and explain, line by line, why it's ugly and what the "right" version would look like.

That's the thing about technical debt: it's honest. You signed for the loan. You know roughly how much you borrowed, and you usually have some idea of when you'll pay it back.

Diff debt is the debt you never read the terms on

Now picture a different situation. A PR lands. 400 lines. Tests pass, CI's green, it's late, and it came from someone (or something) you trust. You scroll through it, nothing jumps out, you approve.

You didn't take a shortcut. You just didn't really read it.

That code is in production now, and if it breaks next month, here's what you'll find out: nobody on the team can actually explain it. Not because it's clever, but because no human ever built a model of it in their head. It got generated or copy-pasted or waved through, and now you're not debugging a bug, you're reverse-engineering a decision that nobody actually made.

That's diff debt. Technical debt is a mess you chose. Diff debt is a mystery you inherited from your own repo.

Where they actually split

	Technical Debt	Diff Debt
How you got it	Chose a shortcut	Skipped the reading
Do you understand the code?	Yes	No
Do you know how deep you're in?	Roughly, yes	No idea until it bites
Can you plan the payoff?	Usually	You don't know it's there

The reason this matters: technical debt sits on your balance sheet where you can see it and schedule it into a sprint. Diff debt is off the books completely, right up until an incident drags it into the light. You can't prioritize a liability you don't know you have.

Why this got so much worse recently

For most of the history of writing software, diff debt barely existed, because producing code was the slow part. If a person wrote 400 lines, a person understood 400 lines. Making the diff and understanding the diff cost about the same.

AI broke that. A clean, confident, tested-looking 400-line change can show up in seconds now, and it's practically engineered to look mergeable. But reviewing it didn't get any faster. If anything it got harder, because generated code stays confident even when it's quietly wrong.

So the pressure to just ship it is huge. The diff looks right, the pipeline's green, click merge. And every time that happens without anyone really reading it, you're not saving time. You're borrowing it at a rate you can't see.

How to tell if your team has it

You've got diff debt if any of this sounds familiar:

A PR gets approved faster than a human could have read it.
There's a 500-line diff with a two-minute "LGTM" on it.
Something breaks and the answer to "who wrote this?" is a shrug, or a tool's name.
There's a file nobody wants to touch, and it got merged in one shot rather than built up over time.

Notice none of this is about code quality. Beautiful code can be pure diff debt. The tell isn't how it reads, it's whether there's a mind behind it.

Paying it down

You fix technical debt by refactoring. Diff debt is different, because the only real cure is understanding, and the cheapest time to buy that is before you merge.

A few things that help: make an approval actually mean "I understood this," not "I didn't spot anything scary." Keep diffs small enough to read, no matter who or what produced them. And when the author is a model, still make someone walk through why the change is correct. If nobody can, that's not a green light. That's the interest showing up early.

So, not the same thing

Technical debt is a loan you took out with your eyes open. Diff debt is one you signed without reading, and the ugly part is you might not find out you signed it until it's due.

A diff you didn't read is a bill you never held up to the light: it spends just fine, right up until the one time it doesn't.

Both cost you. But at least with technical debt, you know you're in it.

Diff Debt: Every AI-Generated PR You Merge Without Reading Is a Loan

Erdi BAY — Thu, 09 Jul 2026 05:24:58 +0000

diff debt (n.) — the accumulated risk of merging AI-generated diffs that no human has actually read.

I shipped code I've never read. So did you.

Here's a confession. A few months ago I built a desktop automation bot called Erci — GUI, computer vision, license system, the whole thing. It works. People use it. And I have never truly read most of its code.

I'm not even a professional developer. I described what I wanted to an AI assistant, it produced the code, I ran it, and when it worked, I moved on. Thousands of lines accumulated this way. The bot is great — until something breaks in a module I've technically "owned" for months, and I open the file and realize I'm reading it for the first time.

If you're a professional developer, your version of this story is more subtle but structurally identical: the agent produces a plausible 900-line diff, the checks are green, the sprint is on fire, you skim, you approve, you merge. The pull request looked perfect. That's exactly the problem — it looked perfect.

I started calling this diff debt: the gap between what was merged and what was actually reviewed.

Why it needs its own name

We already have good words for the neighborhood. Technical debt lives in the code — shortcuts you consciously took. Verification debt (a framing AWS CTO Werner Vogels pushed at re:Invent 2025) is the macro cost of inadequately checking AI output. Comprehension debt (Addy Osmani's term) is the erosion of the mental model you used to build for free just by writing code yourself.

Diff debt is the unit-level version. It accrues one unread pull request at a time, which is exactly why it's invisible: no single skimmed diff feels like a decision. Nobody chooses to stop understanding their codebase. It happens 400 green-checked lines at a time.

The math got broken

Generation got fast. Review didn't.

An engineer writing 500 lines by hand builds understanding as a side effect of writing. An agent producing 5,000 lines in six minutes produces zero understanding — that work is now a separate, unpaid job called review, and the numbers say it isn't happening:

Sonar's 2026 survey of 1,100+ developers found roughly 42% of committed code is now AI-generated — projected to hit 65% by 2027.
The same survey: 96% of developers don't fully trust AI-generated code to be correct, yet only about half always check it before committing. That spread between distrust and verification is diff debt accruing in real time.
Since AI tool adoption, average PR sizes have roughly tripled in many orgs — diffs that used to be 100–200 lines now arrive at 400–600. A 400-line diff can be read. A 4,000-line diff can only be skimmed.

How the interest compounds

Like financial debt, diff debt charges interest. Unread code becomes the foundation for the next unread diff. Six months later a production incident lands at 2 a.m. in a module that "someone" reviewed, and the debugging session costs more than writing the feature from scratch would have. Refactors stall because nobody can predict what breaks. Onboarding slows because there's no one to ask — the author was a model, and the reviewer was a glance.

Paying it down

You can't read everything; the volume math doesn't allow it anymore. Paying down diff debt means spending review attention where wrongness is expensive:

Risk-tier your reviews. Anything touching money, auth, data deletion, or external side effects gets a real human read. Boilerplate can pass on green checks.
Cap diff size. If the agent hands you 4,000 lines, make it deliver in reviewable increments. Reviewability is a feature; demand it.
Demand tests that encode intent — not tests the model wrote to flatter its own implementation.
Track comprehension like a metric. If nobody on the team can explain a module, treat it as an outage waiting for a date.

The teams that win the next few years won't be the ones that generate the most code. They'll be the ones that know, with confidence, what's actually in theirs.

I documented the full definition at diffdebt.com. If your team has its own name for this, I'd genuinely like to hear it.