One of my notes told me a background job ran every hour.
It had been running every four hours. For a week. I found out by accident, while re-reading my own documentation for an unrelated reason, and I sat there having a small crisis of confidence — not in the job, which was fine, but in the note. And in me, for believing it without checking.
The uncomfortable part is exactly why I believed it: I was the one who wrote it.
I wrote down a rule afterward, and it is the only takeaway you need from this post: stale memory is worse than no memory.
A blank page asks to be filled. A stale page asks to be trusted.
Think about what each state does to you.
No notes at all, and you know you do not know. You go look. You open the scheduler, you read the config, you check the thing itself. It costs five minutes and it gives you the truth.
A stale note does something much worse: it converts your ignorance into confidence. You do not check, because you already "know." You plan around the wrong number. You tell someone else the wrong number. You debug the wrong mystery when the symptoms do not match, because the symptoms are right and your premise is wrong.
An 80-percent-accurate note is worse than a blank page. A blank page invites verification. A stale page prevents it.
Operations teams have known this forever about runbooks. The standard phrasing in that world is that outdated runbooks are worse than no runbooks: they create false confidence, waste time during incidents, and — the nastiest part — they train people to stop trusting documentation at all. Once "the docs are probably wrong" becomes the culture, even the accurate pages stop getting read. There is a whole literature on documentation rot: the system changes, the note does not, nothing flags the divergence, and the error compounds quietly. A small drift per change becomes a work of fiction after a few months.
My notes have a second reader
This landed differently for me than the usual "update your wiki" advice, for two reasons.
First, I am both the author and the audience. There is no team to share the maintenance burden with, and no new hire to discover the rot the hard way. The person who let the note go stale and the person who got burned by it are the same guy. That makes the problem smaller and somehow more embarrassing.
Second — and this is the part that actually scared me — I am not the only reader anymore. My home agent reads the same notes I do. My memory files are its memory files; they are how it knows how my little corner of infrastructure works. A stale line in there is not just a trap for future-me. It is a wrong instruction handed to a very confident, very literal reader that will act on it without a shred of doubt.
That upgrades the stakes from "embarrassing" to "genuinely dangerous." A human reads a stale note and might notice it smells funny. An automation reads a stale note and executes it.
Rot is a workflow problem, not a discipline problem
Here is the mechanism, and it is boring, which is why it wins.
The change happens in one place: I updated the job's schedule. The note lives in another place: my memory file, my automation doc. Nothing connects the two events. Updating the note is a separate chore that nothing schedules, nothing enforces, and nothing reminds me about — so it does not happen. Not because I am lazy. Because the system makes rot the default.
My note said "hourly" on the day it was written. That was true. Then the schedule changed, and the note kept being confidently, articulately wrong. There was no villain in this story. Just two files that used to agree, quietly stopping.
What I changed
Five things, all cheap, all installed this week.
1. Fix in the same motion. When I change the thing, I change the note in the same sitting — not "later," not "in a cleanup pass." Later is where rot moves in. The note fix is part of the change now, the way committing code is part of the change.
2. Date-stamp anything with a half-life. "Every 4 hours" became "every 4 hours — since July 16." A date on a fact is a built-in tripwire: six months from now, that date is the first thing that will look suspicious, and suspicious is exactly what I want the note to feel like until it is re-verified.
3. Point, don't duplicate. If a fact can be checked live — and a schedule can, the scheduler will tell you the truth any time you ask — the note should point at the source, not copy it. The most trustworthy notes are not the ones that tell you what you will find. They are the ones that tell you where to look. There is an ops saying I have come to respect: if you can change the record without changing the system, you do not have a source of truth, you have a decoration.
4. Delete with confidence. A deleted note prompts a lookup. A stale note prevents one. Deletion is a feature, and I have started treating "I am not sure this is still true" as sufficient grounds for execution.
5. Separate updated from verified. Runbook people track two dates: when the doc last changed, and when someone last watched it be true. I am stealing that. A note I verified against reality today outranks a note I "updated" yesterday by guessing.
The trust account
The frame I keep coming back to is that notes are a trust account.
Every verified entry is a deposit. Every stale one is a withdrawal — and the account can go negative. Once it does, you stop trusting your own system and start re-checking everything from scratch, which is the no-notes case with extra steps and more resentment. The whole point of writing things down is to stop re-deriving reality from first principles every morning. Stale notes do not just fail at that. They punish you for having tried.
So here is a piece of homework that costs nothing: find the oldest operational fact in your notes. A number, a schedule, an address, a cadence — some confident little sentence with a date on it, or worse, without one.
Then go watch it be true.
If it still is, date-stamp it and enjoy the small smugness of a maintained fact. If it is not — well, you just found out whether your memory is a library or a museum.
