Technical debt you cannot see: measuring cognitive debt

The most expensive technical debt is the rule only one person can explain. A 40 minute test to find that concentration, and what to do once it shows up.

The most expensive rule in the company usually lives in two places: this whiteboard and one person's head

The technical debt slowing your roadmap is rarely the ugly file. It is who can explain that file. You can measure it this afternoon, in about forty minutes: write down the ten business rules that touch money at your company (how the discount is calculated, when an order can be cancelled, what releases a partner payout) and put next to each one the name of the person who can explain it without opening the code. If one name shows up on four or more lines, that name is more expensive than any badly written module you own.

The cost hits the calendar before it hits the codebase. Every task that touches that rule joins one person's queue. Estimates start to depend on her schedule, the review that actually matters happens when she has time, and the week she finally takes the vacation she has been rolling over, the roadmap moves on leftovers. That is technical debt in the only definition a person signing payroll cares about, which is why I keep saying tech debt is a risk spreadsheet, not an engineering complaint: cost, schedule, revenue.

Quantifying technical debt is the question the internet never answered well

With an agent the change ships in forty minutes and nobody new learned the rule

On Software Engineering Stack Exchange, "How can I quantify the amount of technical debt that exists in a project?" has been viewed 20,433 times and collected 12 answers. Its neighbour, on how to convince management to deal with technical debt, sits at score 176 and close to 19,000 views. Two questions more than a decade old, fresh traffic every month, and nearly every answer offering a code metric: cyclomatic complexity, test coverage, code smell counts.

None of those metrics explains why nobody can touch the commission logic without pulling in one specific engineer.

The list of names does. It is crude, it fits on a napkin, and a non technical board member understands the result without translation. That is roughly why shiftmag pulled 75 points and 72 comments on Hacker News with a piece arguing cognitive debt is the new technical debt. The phenomenon is old. What was missing was a name for the part the static analyzer cannot see.

A clean board is usually the symptom

An all senior team barely documents anything. It is not laziness. Nobody ever has to explain anything to anybody: everyone was in the room when the rule was written, the decision came out of a ten minute call, and the commit captured the how without a single line of the why. Delivery lands on time, the board looks clean, and the most expensive knowledge in the company quietly concentrates in three or four heads that understand each other a little too well.

In the systems that land on my desk after the previous vendor walked away, the thing that slows the first month is not the chained slow query or the test suite without a single assertion. It is figuring out why a strange conditional exists in the order service. That conditional is a commercial agreement someone closed on the phone in 2019. The ugly code was the only living documentation of the business rules, and nobody reads living documentation at the speed a customer expects. It is the same reason a founder with a technical background and a founder without one need to learn each other's job before this bill comes due.

"But we do have documentation"

Half a page of why beats the entire Confluence space written at kickoff

That is the sentence I get the moment I raise this in a meeting. And something usually does exist: a Confluence space, a README, a diagram someone drew at kickoff. The document describes what the system was supposed to do. The code describes what it does. The missing third piece is why the two drifted apart.

Construction has a word for this. There is the design, drawn before anything is poured, and there is the as built, the drawing of how the structure actually ended up after every decision made on site, including the beam that moved because the soil did not cooperate. Skip the as built and you find the deviation by opening a wall with the building already occupied. Software has the same problem with one extra twist: the wall is invisible, and the person who knew where it was took a job somewhere else.

There is an honest test. Take someone who has never touched that rule and ask for a small change, using the document only. If she finishes without asking anyone anything, your documentation is good. If she opens Slack within twenty minutes, you have a file rather than a document.

AI grew the code queue without growing the queue of people who understand it

LeadDev ran a piece in this same window arguing that AI written code is correct and still costs you more. I agree, and the reason connects straight back to your list of names.

Writing code was always the expensive way to learn a system. Whoever implemented the commission rule spent three days inside it, cursed the git history, and came out able to explain it in a meeting. With an agent the same change ships in forty minutes, passes review, and goes to production. The repository grows, the surface area that needs maintenance grows, and the number of heads that can explain it stays exactly where it was. Six months of that and you are carrying much more system with the same amount of people who understand it.

The tool speeds up someone who already knows what they want, and speeds up the person who does not by the same factor. The difference between those two shows up the first night that code breaks at 2am.

Rotation is cheaper than a wiki

A documentation sprint fixes little and rots fast. What moves the list of names is rotation, in three moves:

• Every task touching a concentrated rule ships as a pair, with the person who does not know it on the keyboard and the person who does only answering questions.
• On call rotates through everyone, with the person who knows the system in the second line rather than the first, because on call is the only moment nobody can postpone the question.
• The rule's owner writes half a page of why, including the options that were thrown out, and that page only counts once somebody else changes the rule reading nothing but it.

This costs money. A pair delivers slower than a senior alone, something like 20% to 30% slower in the first weeks, and the team will complain. That is the price of removing a four line name from your list. In an embedded senior squad we build that into delivery from month one under a technical partnership, because a contract with no continuity built in rewards the opposite behaviour: concentrate the knowledge, ship fast, leave with the key in your pocket. Anyone comparing vendors on hourly rate alone should read the rates and what sits inside them with that in mind.

Where this advice is bad

If you are three people still hunting for customers, concentration is an advantage. Rotation eats the week, pairing doubles the cost of a task, and your real problem is finding out whether anyone will pay. At that stage cognitive debt is cheap debt, the same way MVP technical debt is cheap while the MVP can still die.

The math flips when revenue starts depending on that system, or when the team grows and the person who knows everything becomes everyone's bottleneck. It happens without warning. The first sign is a planning meeting where the same name appears on almost every card, and nobody finds that odd because she always sorts it out.

Book the vacation and watch

Make the list of ten rules this week and keep it somewhere you will find again. Then look at the team's time off calendar. If the person on four of those lines disappears for three weeks, you get, for free, the most honest measurement of cognitive debt that exists: what the team ships without her.

People who approve engineering budgets almost never get a number like that. You get one once a year, and you usually throw it away.