Chapter 12: Review

Cognitive debt

A close cousin of comprehension debt, and many writers use the two as one. Where a difference is drawn, this one is about people rather than code: a team gradually losing its shared picture of how the system works and why.

One person can understand their corner and the team can still have lost the whole. That explains a team that can't make simple changes without breaking things, even with tidy code. It also shows why one person reading more diffs doesn't fix it.

Say it to your agent

“Write docs/decisions/0007-payment-retries.md explaining why we retry payments this way and what we rejected, from the commit history and our conversation. Then each of us reads it and I will quiz the team on it on Friday.”

The workshop

Name a word, or describe what you mean in everyday language.