notes for dev teams · kgai.dev/blog

When a senior leaves, 'we tried that in March' leaves with them

The cheapest comment in code review is "we tried that in March, it falls over when the queue backs up". Five seconds to write. It can save a week of confident work on a dead end. And on most teams exactly one person can write it, because the March attempt lives in their head and nowhere else.

Then that person hands in their notice. The code stays, the git history stays, the wiki stays, and none of them hold the thing that mattered. What was tried, why it failed, what the team decided instead. Four weeks of handover capture a fraction of it, mostly the parts somebody thought to ask about. The rest resurfaces over the next year as re-attempted dead ends, each one rediscovered the expensive way. On an AI dev team the loop runs faster, because agents propose old ideas relentlessly. An LLM reading your queue code will suggest the March approach, and it will sound great, because the person who knew why it wasn't is gone.

The fix that worked for us is blunt. Keep "we tried that" in a store, not a head. kgai, the MIT-licensed tool we build, records decisions into an append-only, immutable decision log as the work happens. Capture sits at the write boundary, a skill and hooks in the Claude Code plugin record while the agent makes the change, so the March attempt gets written down in March, by the session that made it, not reconstructed in an exit interview.

Dead ends stay queryable with the reason they failed. When the constraint really does change, say the queue gets rebuilt, a new decision supersedes the old one through an explicit link with a reason and the chain stays intact. Recall returns only decisions in force, so agents act on current truth, while the full history stays one query away for whoever asks how things got this way.

And the store outlives everyone on the team. It syncs, opt-in, through an S3 bucket you own, every machine holding the whole graph, no server anywhere in the path. When the senior leaves, their decisions stay behind with their reasons attached, and the next agent to touch the queue reads them before editing. Their replacement gets the same history on day one, which changes what onboarding even is, the story in the new dev asked why we skipped Elasticsearch.

You can't back up a colleague, but you can back up their decisions. Start recording while the people who know why are still in the room.

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