Comprehension debt

Comprehension debt, and how to pay it down

Comprehension debt (or cognitive debt) is the gap between the code your agent wrote and what your team understands. Why it grows, why it bites, and how to pay it down as you go.

Technical debt is code you know is wrong. Comprehension debt is code that might be fine, but nobody understands it well enough to say. Some people call it cognitive debt. Either way, it grows fastest when an agent writes the code.

How it builds up

Every change your agent makes is reasonable. You approve it, because it works and you are busy. The understanding you would have built by writing it never gets built. A month later, a bug lands in that code, and nobody can reason about it quickly. That delay is the interest on the debt.

Why it bites

• Incidents take longer, because nobody holds the model of the system.
• Changes get riskier, because nobody knows what relies on what.
• The agent itself gets worse: you cannot correct what you do not understand, so its mistakes compound.

Pay it down as you go

The cheapest time to understand a change is the moment it is made, while the agent still holds the whole context. A few minutes then saves hours later.

deck makes that moment cheap. Your agent shows you the change as a short deck: the situation, the lines that carry it, and the decision, each sentence lighting the code it is about. You ask where it does not add up, and the answer comes back on the lines. You end up understanding the decision, not just having approved it.

A rule of thumb

If you could not explain a change to a teammate in two minutes, ask your agent to show it to you before you merge it.