comprehension debt

comprehension-debt.md

background

the (known) origins of the term "comprehension debt"

Jeremy Twei coined the perfect term for this: comprehension debt. It’s certainly tempting to just move on when the LLM one-shotted something that seems to work. This is the insidious part. The agent doesn’t get tired. It will sprint through implementation after implementation with unwavering confidence. The code looks plausible. The tests pass (or seem to). You’re under pressure to ship. You move on.

symptoms

• volume & verbosity inflation; PRs grow in size, making diffs harder to review & reason about.

• shift from “author knows” to “author curated”; folks merge code they steered but didn’t fully internalize - particularly when delivery pressure is high.

• PR reviews trend towards “syntax checking” over “model checking”; reviewers fail to grasp deep system invariants/regressions while spending time on surface-level issues.

• context rot; long agentic runs accumulate contradictory approaches which confuses author & reviewers.

• weak ownership; if “who understands this end-to-end” isn’t explicit, everyone assumes someone else does.

approach to mitigate

• robust PR reviews; reviewers follow conventional commits. Authors structure changes into atomic commits & stacked PRs. Complex PRs include analysis docs summarizing the nature of the effort. We expect that reviews may take time.

• AI-augmented review; we use LLMs to outline module hierarchies, suggest refactors, and verify assumptions when reading other contributors' code.

• quick feedback loops; we invest in ensuring that we are able to have automated validation of business logic & outcomes.

• ownership; we expect team members to be able to articulate their work and ship in reviewable chunks.

• metrics; as necessary, track review iteration rate, follow-up PRs per PR, Revert rate / hot fixes per PR/epic.

---

related reading

 We find that AI use impairs conceptual understanding, code reading, and debugging abilities, without delivering significant efficiency gains on average.

• "How AI impacts skill formation"

Over time, overwork can impair judgment, increase the likelihood of errors, and make it harder for organizations to distinguish genuine productivity gains from unsustainable intensity.

• AI Doesn’t Reduce Work—It Intensifies It

The fundamental challenge is that organizations cannot optimize for what they cannot measure. Velocity is measurable. Comprehension is not, or at least not through any mechanism that currently feeds into performance evaluation, promotion decisions, or headcount planning.

• Cognitive Debt: When Velocity Exceeds Comprehension | rockoder

In this article, I propose a triple debt model for reasoning about software
health, built around three interacting debt types: technical debt refers to problems in the code layer, cognitive debt refers to inadequate understanding across a team, and intent debt refers to a lack of externalized rationale, information that both humans and AI systems need to work safely and efficiently with the code. Technical debt makes systems harder to change. Cognitive debt makes systems harder to understand. Intent debt makes it difficult to know what the system is actually for.

https://arxiv.org/pdf/2603.22106

https://ergosphere.blog/posts/the-machines-are-fine/

https://www.reddit.com/r/ExperiencedDevs/s/4NY3lvKiHY

Code reviews are also different. When I ask "why did you structure it this way?" I often get a blank look. The code works, it looks reasonable, but they cannot explain the reasoning because there was no reasoning. They described what they wanted and the AI produced it.

But the gap between "can produce working code" and "understands what the code is doing" seems wider than it used to be.

The mentoring challenge is real. You cannot teach someone to debug if their instinct is to ask the AI before they think. You cannot teach architecture if they have never had to hold a system in their head. The foundational skills that senior devs built the hard way are just not there.

---

https://www.reddit.com/r/ExperiencedDevs/s/XfcPvgGp05

No business should hire “vibe coders” whose only value is to prompt AI. We don’t need that anymore we have AI agents now that will take a ticket, write code for it, recursively feed the error messages back into AI and generate a PR.

https://aphyr.com/posts/418-the-future-of-everything-is-lies-i-guess-work

https://www.404media.co/software-developers-say-ai-is-rotting-their-brains/

"Bosses Horrified as “AI Native” College Graduates Hit the Workplace
"Massive numbers of students are going to emerge from university with degrees, and into the workforce, who are essentially illiterate.""
https://futurism.com/future-society/college-critical-thinking-ai

https://hachyderm.io/@mitchellh/116580433508108130

I strongly believe there are entire companies right now under heavy AI psychosis and its impossible to have rational conversations about it with them. I can't name any specific people because they include personal friends I deeply respect, but I worry about how this plays out.

I lived through the great MTBF vs MTTR (mean-time-between-failure vs. mean-time-to-recovery) reckoning of infrastructure during the transition to cloud and cloud automation. All those arguments are rearing their ugly heads again but now its... the whole software development industry (maybe the whole world, really).

It's frightening, because the psychosis folks operate under an almost absolute "MTTR is all you need" mentality: "its fine to ship bugs because the agents will fix them so quickly and at a scale humans can't do!" We learned in infrastructure that MTTR is great but you can't yeet resilient systems entirely.

The main issue is I don't even know how to bring this up to people I know personally, because bringing this topic up leads to immediately dismissals like "no no, it has full test coverage" or "bug reports are going down" or something, which just don't paint the whole picture.

We already learned this lesson once in infrastructure: you can automate yourself into a very resilient catastrophe machine. Systems can appear healthy by local metrics while globally becoming incomprehensible. Bug reports can go down while latent risk explodes. Test coverage can rise while semantic understanding falls. Changes happens so fast that nobody notices the underlying architecture decaying.

I worry.

https://mastodon.social/@pojntfx/116580516167414646

One of the best descriptions I've heard lately was that it feels like "losing coworkers to dementia" as people adopt it, where everyone feels like they know everything, but when you talk with them in person or there is a problem that needs to be fixed now it becomes very clear that the capability to do that has atrophied basically completely

https://discuss.systems/@tobinbaker/116580627094675024

that's an interesting analogy, feels like both vibecoding and "resilience engineering" tend to mask systemic risk by superficially and temporarily mitigating the symptoms

https://mastodon.social/@slacy/116580749844092232

story I've heard is the "well, we just rewrite the entire thing every six months so there's no point in fixing/improving because the next iteration/generation will be that much better as the agents improve."

I can actually sort of see this, and it's somewhat along the lines of "spec-driven-development" but ... ?

https://berlin.social/@jnfrd/116581079155866158

yep. Because specs that covered everything (aka waterfall) failed so perfectly before. Why not try it again, this time with an algorithm that has no comprehension to tell you that your spec is trash.

"Anti-distillation for employee Skills."
https://github.com/leilei926524-tech/anti-distill

"The AI Great Leap Forward
Apr 5, 2026 • Han Lee | 12 min read (2193 words)  

In 1958, Mao ordered every village in China to produce steel. Farmers melted down their cooking pots in backyard furnaces and reported spectacular numbers. The steel was useless. The crops rotted. Thirty million people starved.

In 2026, every other company is having top down mandate on AI transformation.

Same energy."

https://leehanchung.github.io/blogs/2026/04/05/the-ai-great-leap-forward/

"A non-anthropomorphized view of LLMs"
http://addxorrol.blogspot.com/2025/07/a-non-anthropomorphized-view-of-llms.html#:~:text=A%20non%2Danthropomorphized%20view%20of%20LLMs

Instead of saying "we cannot ensure that no harmful sequences will be generated by our function, partially because we don't know how to specify and enumerate harmful sequences", we talk about "behaviors", "ethical constraints", and "harmful actions in pursuit of their goals". All of these are anthropocentric concepts that - in my mind - do not apply to functions or other mathematical objects. And using them muddles the discussion, and our thinking about what we're doing when we create, analyze, deploy and monitor LLMs.

https://zirk.us/@LJ/116609499914539590

You learn by doing. With intentional practice.

That's it. The whole deal with creativity is that the process helps you grow. No process? No growth.

Using these tools shortcuts the process. They creat an outcome but don't create an artist. We can argue about quality from now to the heat death of the universe, but unless you engage in the process, you will never develop as an artist.

Whatever "voice" this LLM is leading the writer to, it sure as shit isn't their voice.

https://www.reddit.com/r/cscareerquestions/s/XBfsaiMpN0

"The search engine no longer says “here, go read what this person wrote.” It now says “here, I’ve already read it for you.” The contract is broken.

What's the deal when everyone can just access anything without caring about where it's coming from?

I, for one, enjoy a human touch. I enjoy craft and care. I enjoy the tiny details. I like the idea of a human putting in the work. Regardless of whether it's writing, speaking, recording... I'm online for seeing "the good stuff". And I agree with Mat's take.

why should anyone care about reading something nobody cared enough to write?"
https://webweekly.email/archive/web-weekly-193/

"But that output will be wrong in subtler and more nuanced ways across potentially fatter piles of code with more unrelated output and unwanted dependencies. It will require a more specialized set of skills to identify errors. And those errors will be different every time the code is generated."

https://adrianroselli.com/2026/05/maybe-dont-rely-on-googles-modern-web-guidance.html

#accessibilty