Skip to content

Instantly share code, notes, and snippets.

@graste
Forked from rossdm/comprehension-debt.md
Created April 3, 2026 15:35
Show Gist options
  • Select an option

  • Save graste/a0674ae57dc3466998d88334620560b5 to your computer and use it in GitHub Desktop.

Select an option

Save graste/a0674ae57dc3466998d88334620560b5 to your computer and use it in GitHub Desktop.
comprehension debt

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.

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.

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.

@graste

graste commented May 22, 2026

Copy link
Copy Markdown
Author

@graste

graste commented May 26, 2026

Copy link
Copy Markdown
Author

"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/

@graste

graste commented May 28, 2026

Copy link
Copy Markdown
Author

"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

@graste

graste commented Jun 17, 2026 •

Copy link
Copy Markdown
Author

"My Students Can’t Read"

https://www.chronicle.com/article/my-students-cant-read

"The generational collapse in literacy is measurable, persistent, and likely to get worse."

Rhetoric and writing students that lose track reading a 20-page article. 😳

"When I assign analysis, I am not trying to extract a polished product; I am trying to put the student’s mind through resistance in order to make it stronger. Offloading the struggle to a chatbot does not “free students up for higher-order work.” It deprives them of building the strength to do any substantial cognitive work at all."

"The ability to read deeply and reason at length is fragmenting along class lines as ultra-processed digital media replaces text in everyday life, much as ultra-processed food has replaced cooking."

"My students from districts that protected sustained reading through small class sizes, strict phone policies, and faculty who refused to teach to the test all arrive with their attention relatively intact. My students from districts that surrendered to devices and standardized testing arrive cognitively winded. A democracy that requires a literate electorate is now training one fraction of that electorate out of literacy while marketing to the other a “deep work” lifestyle as a luxury good. The students who cannot read a 20-page article today are the voters who will not be able to read a bill, or the jurors who cannot follow a closing argument, tomorrow."

@graste

graste commented Jun 18, 2026

Copy link
Copy Markdown
Author

"Benjamin Piel, Chefredakteur vom "Weser Kurier", schreibt in einem Kommentar für "Kress" über die "Dumm-Nutzung" und "Schlau-Nutzung" von KI-Systemen.

Er schreibt:

"Die Dumm-Nutzung der KI ist, (…), sie die Hausaufgaben erledigen zu lassen. Das bringt zwar verlässlichen Kurzfrist-Erfolg, führt aber zur Verblödung."

Aber er schreibt auch:

"Wer am Ende des Schreibprozesses eine intensive Redigatur verlangt, bekommt sie mit dem richtigen Prompt von kaum jemandem so gnadenlos und sortiert wie von der KI.""

https://www.mdr.de/altpapier/das-altpapier-ki-journalismus-einsatz-vertrauen-glaubwuerdigkeit-100.html

@graste

graste commented Jun 20, 2026 •

Copy link
Copy Markdown
Author

"CTOs Agree: Cognitive Debt Is the New Technical Debt"

https://shiftmag.dev/ctos-agree-cognitive-debt-is-the-new-technical-debt-10229/

"The room had seen the same pattern: teams adding features at a pace that would have been impossible two years ago, now dealing with the maintenance overhead that comes with it. Legacy code that was already hard to understand is now harder, because the people who wrote it aren’t being careful."

"write whatever you want, but writing it doesn’t mean you’re shipping it. Code is cheap, but launching it isn’t."

"if anyone can ship, whose job is it to hold everything together? Several people in the room said the only realistic response is radical team autonomy: small groups of three to five people who own their own decisions, with management’s job shifting to alignment rather than gatekeeping."

"The deeper point was about abstraction layers. We don’t read assembly, we trust compilers. The question is whether you can build enough validation infrastructure, feature flags, observability, acceptance tests, mutation testing, to make a similar trust relationship work with AI-generated code."

"The cost of building AI features isn’t the hard part. The cost of verification is. If you build a solid eval suite today, you can swap providers, survive model deprecations, or move to open source without starting from scratch"

@graste

graste commented Jun 30, 2026

Copy link
Copy Markdown
Author

"To a senior developer, AI is a competent, fast-working junior or mid-level developer that, when properly directed, produces mostly solid work but lacks the institutional knowledge and the deep and broad systems-level knowledge that you have developed over the past twenty years."

https://adiamond.me/2026/06/software-engineering-in-the-age-of-ai/

"The novelist, like the software engineer, is no longer deeply engaged in her work. Editing is not creating. You do not give yourself over to your imagination. You do not immerse your mind and feelings in the process of invention. Instead, you’re rooting out problems, trying to clean up clumsy wording and redundant descriptions instead. The flow state is gone. You are now a cog in a larger process that doesn’t really value your creativity or your need to exercise it.

Worse still–and I have felt this personally after months of reviewing AI-generated code–your skills drop off sharply."

@graste

graste commented Jun 30, 2026

Copy link
Copy Markdown
Author

https://news.ycombinator.com/item?id=48710554

I write code myself and use the LLM to find mistakes then fix them manually. I recommend inverting the conventional wisdom on LLMs:

  1. Don't use it to write code. It's a terrible
    programmer. But it's an intelligent rubber duck
    and a solid analysis tool.

  2. Write the code yourself. It'll go faster than
    figuring it out as you go along. It's just typing
    if you have a plan.

  3. Use an LLM to sanity check what you wrote.
    It can find potential design issues or future
    problems or breaks from convention. Decide based on
    your experience how much you want to address these
    issues before moving on.
    Is this as fast as AI writing the code? Not at first but possibly over time. Maybe faster. Certainly better quality.
    Plus you don't lose any of your skills in the process.

You're still doing the gruntwork necessary to keep your skillset.

And the token cost is a small fraction of what it takes to get LLMs to write good code.

@graste

graste commented Jul 7, 2026

Copy link
Copy Markdown
Author

"The alternative he proposed is a ratio: customer value delivered against the total cost of producing it, headcount, tooling, and token spend included. DORA metrics and PR throughput are not useless, he argued, but they measure the inside of the system, not its output. Treating them as primary goals disconnects engineering effort from the outcomes the business actually cares about."

"analysis found that when controlling for pull request size, AI has a negligible independent effect on defect rates. The actual driver is that AI generates larger pull requests, and larger pull requests correlate with more bugs. That is, in principle, actionable: you don’t need to focus on the AI generated code, but to the PR scope discipline."

"Code review is absorbing the strain more visibly. Poletto cited 30 percent more rework time on AI-generated code compared to human-generated code, along with more review round trips."

https://shiftmag.dev/ai-generates-larger-pull-requests-larger-pull-requests-bring-more-bugs-9932/

@graste

graste commented Jul 9, 2026

Copy link
Copy Markdown
Author

“The craftsmen are tired,” he wrote. “Day after day, their workload grows. Bugs seep into production. No one seems to care. Another round of AI is thrown at it. Their animosity to their colleagues rises.” 

“Eventually, they give up,” he added. “The craft they loved is dead.”

https://futurism.com/artificial-intelligence/software-engineers-crisis-drown-ai-code

@graste

graste commented Jul 13, 2026

Copy link
Copy Markdown
Author

"Anthropic is actively campaigning to end software engineering. They need you to believe they can do that. Well, maybe it’s not you that they need to convince. Maybe it’s your C-Suite, various world leaders, or the manager of your retirement fund. They’ve raised $132 billion in investment, and are approaching an IPO valued over $1 trillion. Since they cannot show profitability, this depends on selling their hypothetical future impact."

https://raymyers.org/post/zig-creator-calls-spade-a-spade/

"Anthropic needs people to believe that all problems can be solved by adding more agents, even the problems that agents introduce. Instead of better tools we buy tokens. Instead of learning skills we paste a SKILL.md. Instead of reading about The Psychology of Software Teams we call some parallel agent sessions a Team."

@graste

graste commented Jul 22, 2026 •

Copy link
Copy Markdown
Author

AI Coding will Prevent Expertise

The need for ongoing friction in long-term skill formation.

https://larsfaye.com/articles/ai-coding-will-prevent-expertise

"Coding/programming/software is a unique intersection of logic, math, problem-solving, critical thinking, planning, communication, and creativity."

"My AI-assistance checklist:

  • If I did not have access to an AI tool, could I still accomplish this task?
  • Am I using the model to deepen my understanding, or expedite the answer?
  • If I had to audit and verify the generated output, could I adequately explain what was happening?
  • If I'm learning a new concept, have I done proper research to know the right questions to ask?
  • Have I cross-referenced and verified the approach through other methods (reading documentation, standard search tools, StackOverflow, Reddit)?
  • Is this a truly rote task that's been done 100 times before, or a task that requires executive decision-making somewhere in the process?"

"The key is to detect the difference between cognitive debt and cognitive offloading: Cognitive debt is abdicating your judgment and decisions, whereas cognitive offloading is delegating the mechanical or tedious."

"The realignment I hope to see over the years is the understanding that skills don't develop without active participation. You must engage directly and continously to experience the essential friction that culminates in expertise (even if it means moving more slowly)."

@graste

graste commented Aug 16, 2026

Copy link
Copy Markdown
Author

"The problem is that code produced by an AI agent looks reasonable, but can contain ‘hard-to-spot bugs’ that end up causing major problems. As a result, you should carefully review your agent’s output, but this is difficult. As the engineer told me, it’s “famously hard” to understand code you didn’t write yourself, so this extra step becomes “easy to just blow it off (especially when we are all trying to ‘10x’ our velocity).” Soon, systems start to break.

“The coding harnesses are useful and make life as a developer easier,” he summarized, “but they also encourage laziness.”"

https://calnewport.com/on-ai-coding-and-its-discontents/

@graste

graste commented Aug 20, 2026

Copy link
Copy Markdown
Author

"The skills that didn't go anywhere"

https://ryangjchandler.co.uk/posts/the-skills-that-didnt-go-anywhere

"The codebase is a fixed input, but everything around it changes weekly. Priorities shift, a customer churns, someone makes a decision in Slack that quietly invalidates the plan from a fortnight ago. You're carrying a model of the system that updates continuously, and the agent starts every session with none of it.

So you're not just handing over a problem. You're handing over the conditions that make one solution correct and another one technically fine but wrong for you."

@graste

graste commented Aug 20, 2026

Copy link
Copy Markdown
Author

"“Writing is a technology for thinking,” cognitive psychologist Ronald T. Kellogg told the New York Times in a new essay mulling the consequences of sidestepping the hard work of writing.

Writing, the piece notes, helps develop all sorts of cognitive faculties, including building our working memory, executive planning skills, and our metacognition, or the ability to be aware of your own thinking."

https://futurism.com/future-society/students-lose-ability-think-ai

@graste

graste commented Aug 29, 2026

Copy link
Copy Markdown
Author

@graste

graste commented Sep 8, 2026 •

Copy link
Copy Markdown
Author

"This Fence Has No Farmer
Every developer inherits code nobody can explain. The old assumption, that someone had a reason for it, is getting harder to trust. Pondering Chesterton's Fence and AI code."
https://adamgreenough.net/blog/this-fence-has-no-farmer/#:~:text=This%20Fence%20Has,and%20AI%20code.

"We're creating more unexplained code at the same time as we're creating better tools for explaining code. The same thing that's making the archaeological layer thicker is giving us a pretty good shovel.

Which ties back nicely to something I wrote a while back, Our Clients Are Using AI Now: users were never going to wait around for developers to bring AI into the workflow, and plenty of them are already in there themselves. This is just what that looks like a few months on, showing up as actual code in actual production sites, WordPress or otherwise.

The bit of the job that still matters most was never writing the code in the first place. It's knowing what you're looking at, working out what it does, deciding whether that fence still needs to be there and, increasingly, accepting that there may not have been a farmer at all."

@graste

graste commented Sep 8, 2026

Copy link
Copy Markdown
Author

"I stopped using the AI chat because it became very clear it wasn't helpful or healthy, and it was in fact dangerous. But I kept using AI for coding at work, using it to take on more and more of the heavy-lifting to the point where I was just a code reviewer and a quality assurance tester for the features the coding harness would spit out. Getting a lot of tasks done, it can feel exhilarating. That is, until I realized, well, I'm basically just a hamster on a wheel, checking boxes, getting tickets done with no real purpose. Sure, I catch an issue here or there. But it's impossible to review the quantity of code the AI writes, and we've got a different AI to review it anyway! So what did this do? Well, it made me lazy. It made me stop caring. It made me a worse programmer. It made me depressed. Because I stopped doing the hard work, I stopped learning, I stopped growing, I stopped being the one making the software."

https://brettcodes.com/im-done-using-ai/#:~:text=I%20stopped%20using,making%20the%20software.

So in summary: using AI for coding led to depression, apathy, existential dread, and worse software. Not good. Add on top of that the negative environmental, community, and economic impacts of AI, and it became extremely apparent to me that something's gotta change.

@graste

graste commented Sep 8, 2026

Copy link
Copy Markdown
Author

But there is now a scenario in which an autonomous AI harness, backed by an enormous amount of computational resources, performs this entire iteration internally, and ends up producing the final ansatz, and thence the solution to the Navier-Stokes regularity problem, while the AI company running the harness keeps the process to arrive at that ansatz almost completely out of public view. Technically, one of the most prominent open problems in mathematics would now be solved; but there would be almost no value added to mathematics as a consequence. It is theoretically possible that with some herculean (and heavily AI-assisted) additional effort by a third party, some portion of the process could be reverse-engineered to recover some actual insight and understanding from the solution; but this would be a far less efficient process than if the solution had been obtained via a diverse combination of both human mathematicians and machine assistance as mentioned above. (5/6)

https://mathstodon.xyz/@tao/117207855800042681

@graste

graste commented Sep 21, 2026

Copy link
Copy Markdown
Author

https://infosec.exchange/@isotopp/117305270285890280

The specialization workflow, as outlined in the blog article, works by producing a structured user-stories document in interaction with the model,

then turning this into a sequence of actionable tickets that already discuss testing using a TDD skill,

and then processing these tickets during a code-gen phase into actual code, again using a red-green testing workflow.

This is pretty much mirroring the process that any product owner or technical program manager uses to collect requirements, turn them into implementable tickets and then handing them off to humans. It is using the same tooling, language and acceptance criteria, to achieve results.

Human dev teams, from the point of view of a PO or TPM, are also non-deterministic and deliver a codebase the receiver - the PO or TPM - does not understand or trust, and where the same mechanism used with a human dev team to gain trust into a codebase can be applied to the results from a codegen.

So from the PoV of a PO/TPM, nothing much has changed.

Except maybe the fact that they now can cheaply re-run the pipeline and get differing, competing implementations and measure results - which was usually not within financial range for most organizations.

The workflows are pretty much symmetrical, the main difference being that the human devs at the end of that pipeline have been replaced by a code generator. A code generator, which delivers acceptable results for many problem spaces when held "right" (i.e. in a process that looks like outlined above, or similar - chatto.run for example uses a different process with comparable results at a much larger scale).

chatto.run is interesting, because it also shows the importance and the role of documentation to enable a code generator to do the right thing, i.e. produce code that implements the right ideoms for the target problem space: Chatto is too new to be in the learned corpus of a code generator model, yet the documentation found and searched by the model enabled it to produce https://github.com/isotopp/chatto-threaddump successfully in a one-shot attempt.

And no, this is not something that can be solved with a library or any other existing concept in dev-space - iterating on requirements, solidifying requirements into implementable tickets and then putting tickets into code in the target language using target libraries, i.e. integrating tickets and target documentation (more language!) into executable and testable code is not mappable into a library function.

@graste

graste commented Oct 5, 2026

Copy link
Copy Markdown
Author

https://www.reddit.com/r/ClaudeCode/s/Iw4ZhvdR8i

The problem is much worse than we imagine.

The fact that most code had to be typed by hand didn’t just give us leverage. It also meant that our time was protected. Stakeholders would have to choose what they wanted to build, make tradeoffs, or spend capital to grow the team to accommodate more work. This protected us even further by driving up wages and demand for skilled labor.

The cognitive benefit is obvious - we were able to focus and collaborate on smaller surface area, with more scrutiny. And the cost of an abandoned feature or prototype was high, so we were measured and careful.

Now, you can have claude whip up 10 prototypes in parallel, fix the entire backlog, while you’re testing yesterday’s work (and it can do that too).

I used to lament to my parents how much work had accelerated since their days, from manual typewriters and xeroxes, pre-email world to post-slack world. But now we’ve seen another 10x shift - and we’re hitting the limits of what we can realistically cognitively manage.

I’m sure the next generation, if there is one, will be able to context switch effortlessly. But yeah, it’s a different job. I miss the old one. It was just a year ago. And I do love the new one too. But I dont know how much faster we can go. The wetware (us) is the limiting factor now.

@graste

graste commented Oct 5, 2026

Copy link
Copy Markdown
Author

"Junior Developers Can No Longer Write a Working Function Without a Chatbot"
https://blog.pixlab.io/2026/10/junior-developers-can-no-longer-write-a-working-function-without-a-chatbot

@graste

graste commented Oct 9, 2026

Copy link
Copy Markdown
Author

"School district makes dramatic U-turn on AI, banning it across all grades weeks after Google Gemini rollout
New York City has also banned AI for younger students as concerns over classroom use grow"
https://www.techspot.com/news/114151-school-district-makes-dramatic-u-turn-ai-banning.html

@graste

graste commented Oct 10, 2026

Copy link
Copy Markdown
Author

"There is now a growing body of research suggesting that this "cognitive offloading" to AI can have a corrosive effect on our mental abilities. The consequences could be alarming and may even contribute to cognitive decline."

https://www.bbc.com/future/article/20260417-ai-chatbots-could-be-making-you-stupider

"ChatGPT users experienced up to a 55% reduction in brain activity and long term memory degradation compared to those working unaided"

@graste

graste commented Oct 10, 2026

Copy link
Copy Markdown
Author

"Over-reliance on chatbots can diminish critical-thinking skills, study finds"

https://www.theguardian.com/us-news/2026/jun/19/chatbots-critical-thinking-skills

". A 2025 Lancet study found that doctors who use AI classification tools to detect cancer eventually became worse at doing so on their own. A neuroscientist at the Possibility Institute, a metascience research group, recently warned that diverting too much of one’s thinking to AI can weaken the brain’s defenses against dementia.

The recent MIT study’s analysis notes that an AI system’s approach – and whether it’s more prescriptive or probing – can affect a user’s ability to maintain good judgment. Although users are often looking for a chatbot to provide speed and certainty, it’s the more nuanced, guided questioning that can improve critical thinking, the study notes.

Participants who use AI systems that tell them what to do say they often “go along with the system because it sounds knowledgeable”, the study adds. "

@graste

graste commented Oct 10, 2026

Copy link
Copy Markdown
Author

"I get into meetings and I can't watch people start typing everything I say into Claude. They are not able to make decisions by themselves anymore"

@graste

graste commented Oct 22, 2026

Copy link
Copy Markdown
Author

"Nobody is Thinking Anymore"

https://yusufaytas.com/nobody-is-thinking-anymore

"People in different positions rely on LLMs inside companies and even governments. They outsource their decisions only to find out they are actually accountable for them. A strategy document written by AI is pretty much telling the organization what it should be good at, as if we no longer trust ourselves enough to make that judgment. I don't buy that. I want to feel the depth of someone’s actual judgment. I want to know they sat with the problem, walked a bit to take a fresh air, listened to hard feedback, argued with someone over the alternatives, got a bit angry, and ultimately made the imperfect trade-offs themselves. Imperfect is actually good, because we don’t know what’s absolutely right anyway. What matters is that a person stands behind the writing."

@graste

graste commented Nov 8, 2026

Copy link
Copy Markdown
Author

"An Anthropic engineer warns about 'cognitive surrender' as AI agents take over his work"

https://www.businessinsider.com/anthropic-engineer-addy-osmani-cognitive-surrender-warning-2026-11

"Increasingly, nothing in my day-to-day forces critical thinking on me now that so much of my work runs through agents,"

"You have to build critical thinking into your day, because by default nothing will do it for you."

There are three types of diminished thinking with AI use, he wrote. First is "cognitive offloading": the process of delegating tasks to AI while retaining ownership of the products. "I do this all day," he wrote. "You should, too."

The second is "deferral," where AI's output becomes your new input. The third is "cognitive surrender," a term coined by two researchers at the Wharton School. This is complete trust in AI outputs, which Osmani described as lazy. Surrendering too often creates "cognitive debt."

It's not yet clear whether AI is making us dumber or changing the way we think. Researchers Business Insider spoke with saw some bad signs, but cautioned against jumping to conclusions.

As for Osmani, he often sees this surrender of critical thinking. It's not the worst thing, he wrote; it's merely a question of the task's importance.

"Where the stakes are low, feel free to delegate entirely," he wrote. "When you can't explain the answer to a question, even by way of your agent, you've ceded ownership."


"Did I formulate a hypothesis before asking?" and "What am I no longer practicing?"

"verification as a habit"

@graste

graste commented Nov 8, 2026

Copy link
Copy Markdown
Author

https://youtu.be/EkH_uoybj8k

Verification tests outside of agents folder. Spec driven development.

@graste

graste commented Nov 9, 2026

Copy link
Copy Markdown
Author

"The future of Software Engineering is boring"

https://packagemain.tech/p/the-future-of-software-engineering

"My main motto was always to keep the code to a minimum, but AI just can’t do it, it’s only adding things, resulting in bloated codebases, slow builds and tests."

"I can tolerate the AI-generated code, but when the email or a doc is also a slop, you are simply showing a lack of respect."

"We used to spend time solving the problems with code, now we’ve become a caretaker of code that nobody really understands."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment