Why does agent documentation fail?

The most common reason agent documentation fails: Writing documentation once at creation and never touching it again. You'll know you're in this failure mode when someone asks how an agent works and you say 'check the docs' without confidence that the docs reflect reality. The second failure mode is more subtle: updating the agent's behavior but treating the documentation update as a separate, lower-priority task that can wait. It never gets done. The gap between agent and documentation widens with every change until the docs describe a system that no longer exists.

The fix: Pick one agent or automated system you currently maintain. Open its documentation — README, wiki page, inline comments, whatever exists. Read every factual claim: data sources, triggers, dependencies, output destinations, failure modes. For each claim, mark it as current, outdated, or unknown. Count the results. If more than 20% of claims are outdated or unknown, your documentation has decayed past the trust threshold. Now update the outdated claims or, if you cannot verify them, delete them. An accurate gap is better than a confident lie.

The underlying principle is straightforward: Documentation should evolve with the agent — outdated docs are worse than no docs.