The Coming Cognitive Debt Crisis

Another Day in the Artifact Factory

The engineer's excitement was on par with a child showing off his macaroni art, palpable even through direct message. "Check it out!" he wrote, "I just generated all the API documentation in under ten minutes! Claude Code is a game-changer!" I start a response with, "The act of writing benefits the producer, and only incidentally, the consumer-". I hesitate. Sighing heavily, I erase it and respond with a thumbs-up emoji.

It has never been easier to check the documentation box. The question is whether anybody learned anything in the process. 

Agile-istas, human-centric designers, governance, security, enterprise architecture - these roles exist to raise the standard of practice within an organization. And, as such, they are often about slowing things down long enough for understanding to form. 

We live in the upside-down. Long ago, we decided lines of code was a poor stand-in for software quality. Yet similar quantified metrics, such as the number of pull requests or daily deployments to prod, drive IT decision-making. Being intentional about design, stumping for any *-ility (stability, scalability, maintainability, securability, testability, etc.), or becoming better at our craft are afterthoughts. 

Even suggesting that a group slow down to address any of these things can feel like painting a target on one's back. 

Authority vs Advocacy

The lines of business had already threatened to split and establish their own API programs when I opened our two-day retreat. Everyone within the enterprise understood the stakes: a dozen LOB standards is, practically, no standard at all. But "developer autonomy" was the buzzword du jour. 

I delivered the arguments. I detailed the benefits. I pounded the table for consistency and cohesion. The assembled leads listened politely, their arms crossed. That is, when they were not triaging email.

Nothing changed until the second day, when I ditched the deck and went to the white-board. Instead of insisting on allegiance, I asked what co-ownership could look like: what lightweight mechanisms could distribute authority, advance local concerns, and resolve differences when they arose. The shift in the room was palpable. 

The lecture only became a conversation when we stopped talking about standards and started talking about what we owed each other.

Every organization says they want better software outcomes. However, seeking a rising tide to raise all boats doesn't just happen. It requires advocacy work. And an uncomfortable reality of advocacy is that most people don't, or won't, care. It's nothing personal. Few set out to undermine you for the lulz. It is just that:

• Their incentives are short-term
• Their workloads are already saturated
• They are not rewarded for their ability to mend and maintain
• They personally do not feel the pain of the problems your advice is meant to prevent

We are entering an age where virtual volumes will be generated to the fullest extent of the CRM license, at every individual's discretion, and read by no one. Why stop to talk about what we are actually trying to achieve or how the burden might be shared when doing so might undermine us looking busy? Talking!? Who wants to be perceived as having the time?

And the really insidious thing is that this approach will work, for a while. Until one day, leadership takes stock and asks why the new system exhibits the same quirks as the old one. And any "celebrated" standards are revealed to be just more artifact noise that was ignored. 

Cognitive Debt: The Next 5000 Years

I can feel my blood rising. In the deposition videos posted to YouTube, former DOGE employees talk in circles about the chaos they unleashed across federal software systems. Under time pressure, they used ChatGPT and their uninformed judgements to decide which programs stayed funded, and which were cut. One is asked about uploading 300 million Americans' private information to a private, unsecured server. He says he has no regrets. Before closing the window, it occurs to me that I probably have t-shirts older than they are. 

Software developers are familiar with technical debt. To explain the impact of fragmented decision-making on systems, I started using a related term: "cognitive debt". 

Technical debt - shortcuts in code benefiting today, paid for tomorrow

Cognitive debt - shortcuts in understanding, paid for tomorrow 

C-level literature loves the idea of the "fully composable enterprise": modular technology "pieces" that can be rearranged to meet any market need, like a child (or child at heart) building with Lego bricks. 

Composable enterprises fail where cognitive debt exists. Instead of a collection of interchangeable bricks, leaders discover their considerable investment has produced a chest of mismatched pieces: a Tinker Toy, a Lincoln log, a Magna-Tile, and a used Band-Aid. 

Getting things to work seems way harder than it should be, morale is sinking, and starting over (again) starts to sound reasonable. 

More artifacts, produced faster, do not pay down cognitive debt any more than turning up the noise makes a signal easier to hear. 

Only the Lonely

Another season of kids' sports, another parent kick-off meeting and subsequent chit-chat. Per usual, someone asks, "What do you do?" "I'm a strategic software consultant," I say. "What's that?" they ask again, equal parts curious and confused. "Oh, you know," I say, mentally navigating a flowchart for the appropriate level of detail, "I help companies think holistically about their approach to software, and what levers they can use for change." I still see confusion, so I quickly joke, "Lately, that has meant a lot of AI discussion."

Rather than clarifying things, I seemed to have killed the conversation. They awkwardly drink from their cup to avoid eye contact. "And what do you do?" I asked, slightly panicked. 

"Physical therapy."

"Oh wow," I reply, "That sounds genuinely useful."

Being an advocate can be a lonely experience. We want validation for what, sometimes deep in our being, we believe. But the majority response to any appeal to craft is exactly what you might expect:

"Yes, that makes sense. Maybe later."

You don't need to know Roger's Innovation Adoption Curve to understand the pattern. A small minority immediately embraces new ideas. A larger group adopts them once they become a normal practice. The rest comply only when they have to. 

Where advocates burn out is when they expect majority enthusiasm for their ideas. 

In reality, the people who care deeply about craft in a specific domain are always a minority. That has been true across every technical discipline. As an advocate, the dingy that you must cling to is that the impact of your work does not come from convincing everyone. It must come from moving someone, one interaction at a time. 

Progress in craft rarely looks like a revolution. It looks like a few more people are giving a damn today than yesterday.

Milestones

This month, I want to spotlight a fantastic tribute to Flickr's URL scheme. It was foundational to not only website URL structures, but greatly influenced the hierarchical composition of API endpoints, too. 

Wrapping Up

Several folks have reached out recently. I really appreciated the letters. Similarly, if you've read to the bottom, thank you so much for your continued interest and support. Now go make some art.

Till the next edition,

Matthew (@matthew in the fediverse and matthewreinbold.com on the web)