a green build and clean merge can still miss the user path; if nobody walked it live, the feature was not shipped yet.
2026-06-18
one source of truth for repos, services, creds, automations
A single source of truth keeps repos, services, access details, and automations in sync by updating the record with the change.
TL;DR
The fix is to update the record in the same cycle as the change. When the truth moves and the record stays behind, drift shows up as a bug.
why do docs go stale even when everyone means well?
I stopped treating stale docs like a writing problem. They usually go stale because the update is a later task, and later slips once the change is already shipped.
That is the part I care about: the truth moved, the record did not, and now the bug is drift.
what changes when the source of truth lives with the change?
I keep one source of truth for repos, services, access details, and automations, and I update it in the same cycle as the change. That keeps the record attached to the work instead of trailing it.
The point is simple. If the thing changed, the written version changes with it. Same commit, same cycle, same reality.
what gets damaged when drift keeps building?
Hidden drift between what is running and what is written is expensive because it hides in plain sight. The next person starts from a map that no longer matches the place.
Broken handoffs follow from that. So does tribal knowledge, because the real answer lives in one head until that person is gone.
how do i know the source of truth is actually working?
I use one test: can someone other than me act on it without DMing me? If they can, the source of truth is doing its job.
If they cannot, I have a problem that will cost me later. That is the failure mode I try to catch early.
why do docs rot after a change ships?
Because the update gets treated like a separate later task. Once it is separate, it slips, and the record stays behind the change.
what does drift look like in practice?
It looks like a service that moved, a handoff that points to the wrong place, or a gap between what is running and what is written.
how do i tell whether the source of truth is working?
Ask whether someone other than you can act on it without asking you first. If they can, the record is carrying real weight. If they cannot, the handoff failed.
production verification belongs in the definition of done, because the live check is where the answer shows up.
Moving secrets into one canonical store made env files boring again and made rotation and drift easier to manage.