How a Doc Goes Stale
AI wrote one review file per pull request. Four months later, we deleted 80 of them. Why docs that are easy to write still go stale, and why every doc must be easy to change.
In June 2026, one of our services started a new practice. For each pull request, AI wrote a review file and saved it in the repo.
Four months later, we deleted 80 of those files.
Why we deleted them
Each file was a plain-text copy of one moment. It was out of date right after the merge. Nobody read it again. It also added one more gate that we had to maintain.
AI made docs easy to write. But a doc that is easy to write does not stay alive by itself.
The cycle that makes a doc go stale
This cycle has no villain. Each step makes sense, and the doc still goes stale.
Can we avoid technical debt?
Take the best case. You have no deadline, and today your design is perfect. Tomorrow the world changes, and you learn something new.
DIKW (data, information, knowledge, wisdom) puts our work in the knowledge layer. New learning keeps rewriting that layer. So our docs must be easy to change. They are never final.
Change what we expect
| Do not expect | Expect |
|---|---|
| One perfect structure that never needs work, from AI or from a process | If we find a better way, we can refactor the structure |
| Docs that are always correct | A fast way to fix a wrong doc (a recovery step) |
The next step is to list the causes and sort them. Some causes AI can fix, and some it cannot. See Name the Pain Before the Tool.
A doc is never finished. It only goes out of date. So design it to be easy to change.
References
Related: see which causes AI can fix, jump to the reminders that keep docs alive, or go back to the series overview: Docs in the AI Era.