"Wait, I thought we agreed: decision drift between docs and reality"
The architecture doc says all service communication goes through the event queue. It's a good doc, carefully written, and it was true in October. Then the January incident happened, the team agreed to let two hot paths call directly, and everyone updated their mental model. Nobody updated the doc. By spring there are two kinds of engineers, the ones who were in the January call and the ones who read the doc, and they contradict each other in review with total confidence. "Wait, I thought we agreed" is the sound a team makes when its written record and its actual decisions have drifted apart.
Docs drift because a doc is a snapshot of belief at writing time, and belief keeps moving. Nothing in a wiki page tells you whether it still holds, who overrode it, or why. For an AI dev team that's an active hazard, not just friction. The agent can't tell the doc is stale, so it reads it and builds faithfully against a consensus that died in January. The failure looks the same whether the doc is outdated or missing.
What worked for us was making the change of mind a first-class record. In kgai, the MIT-licensed tool we build, decisions live in an append-only, immutable decision log, and a change of mind is a new decision that supersedes the old one through an explicit link with a reason. Nothing is edited in place, so there is no page to silently rot. The October rule and the January exception both exist, connected, dated, with the incident as the stated reason.
Drift can't hide, because current truth is computed, not maintained. Recall returns only decisions in force, so an agent asking about service communication gets January's answer, never October's, while the superseded chain stays one query away for anyone asking how things got here. The graph is a deterministic projection of the log, so every machine that replays it agrees on what's in force. And when two people record genuinely contradictory decisions, that surfaces as a branch you resolve with one new decision, not as two wiki pages quietly disagreeing.
Capture happens at the write boundary, through a skill and hooks in the Claude Code plugin, so the January agreement gets recorded in January by the session that implemented it. The log syncs opt-in through an S3 bucket you own, with the whole graph local on every machine, details in how AI dev teams share what they learn. When the person who remembers the January call leaves, the record stays, see when a senior leaves.
Your docs describe what the team believed once. Keep the decisions somewhere that knows which ones still hold.
Try it on your repo. Two commands, MIT, nothing leaves your machine until you configure a bucket.
See how kgai compares to other tools on the comparison page, or browse the other notes.