notes for dev teams · kgai.dev/blog

Postmortems capture incidents. Who captures the decisions after?

The outage is over. The postmortem ran ninety minutes, the doc is honest and thorough, and near the bottom sits the sentence that actually matters: retries against the payment provider are now capped, because uncapped retries turned a blip into a four hour incident. Everyone nods. The doc gets read for about a week. Then it settles into the postmortem folder next to the forty before it, and nobody opens it again.

That is the quiet failure in postmortem culture. The process is good at producing the corrective decision and bad at keeping it. Postmortems are filed by incident, indexed by date and severity. But the question that comes back later is never "what happened on May 12." It's "why is this retry logic so conservative," asked eight months on by an engineer, or increasingly by an AI agent, staring at code that looks needlessly cautious. The doc holding the answer is findable only by someone who already knows it exists.

So the decision gets unwound. The agent proposes loosening the cap, the reasoning sounds fine, and nothing in its context says a four hour outage already voted no.

This is the gap we built kgai for, so read with that in mind. kgai keeps a team's engineering decisions in an append-only, immutable decision log, projected deterministically into a small graph of the domain elements each decision touched. The retry cap stops being a paragraph on page four of a dated doc. It becomes a decision attached to the retry element itself, and recall finds it by lexical match plus graph traversal, with no embeddings in the read path, whenever a person or an agent asks about that area before changing it.

Capture happens at the write boundary, through a skill and hooks inside the coding session, so the follow-up is recorded while the incident's reasoning is still concrete. When the provider fixes their side and the cap can loosen, you record a new decision, linked explicitly to the one it supersedes with the reason on the link. Recall returns only decisions in force, yet the superseded ones stay queryable, because dead ends are documentation and repeal needs a record too.

There is no daemon and no server. Team sync is opt-in through an S3 bucket you own, and every writer appends to a shard of their own, so parallel writes never produce a textual conflict. It outlasts any postmortem folder: a million decisions across thirty writers' shards still answer a decision lookup in about 100 ms, though recall and free-text search are slower. MIT licensed, shipped as a Claude Code plugin plus a standalone kg CLI.

Your postmortems already produce the decisions. Give them somewhere the next change will actually look.

See how kgai compares to other tools on the comparison page, or browse the other notes.