notes for dev teams · kgai.dev/blog

The playbook commits six artifacts. Where does a reversed decision go?

Week three of a change. Spec committed, plan half built, and the agent on the build stage finds that the queue the intent called for cannot carry the payload size the spec settled on. The team reverses. Someone edits intent.md, the queue-only sentence becomes the new sentence, the commit says "adjust intent", and work continues. Two sessions later a fresh agent reads intent.md and has no way to know a queue-only version ever existed, let alone that it was tried and failed.

Anthropic's AI-native SDLC playbook is a good loop. "Every stage commits an artifact the next stage can read. Together, the intent, the spec, the plan, the diff and the review findings are the audit trail." Six artifacts in all: intent.md, spec.md, plan.md, the diff with its tests, the PR with its review findings, and the incident record that opens the next intent. That is the right shape for agent work, because an agent reads files, not heads.

The playbook also knows where the seam is. Its lagging indicator for the Plan stage is "the number of changes made to the intent.md that are made after the first spec.md commit for the same change." It counts reversals, which is honest, and it counts them as edits in place, which is where the information leaks out. The old line is gone and the reason it was replaced went with it. The metric knows a change of mind happened and nothing about what it was.

A reversal is an event, not an edit. It has a date, an author, a reason and a predecessor. Overwriting the predecessor is the amnesia that makes rules files ratchet, see repeal needs a record, and it is how decision drift between docs and reality begins.

So we add an artifact rather than argue with the playbook. We build kgai, a decision memory for AI dev teams. Decisions land in an append-only, immutable log, and the graph the agent reads is a deterministic projection of it. A reversal is a new decision that supersedes the earlier one through an explicit link carrying the reason. The superseded decision stays queryable, as does every dead end, yet recall returns only decisions in force, so the next session sees what still holds. The read path is lexical matching and graph traversal, no embeddings anywhere in it. No daemon, no server.

Capture happens at the write boundary, through a skill and hooks, in the session that edits intent.md. Team sync is opt-in through an S3 bucket you own, and per-writer shards mean parallel writers never produce a textual conflict. At 1,000,000 decisions across 30 writers' shards a decision lookup still answers in about 100 ms, though recall and free-text search are slower. It is MIT licensed and ships as a Claude Code plugin with a standalone kg CLI.

Keep the six artifacts. Give the seventh, the reversal, a record of its own, and the Plan-stage metric stops measuring a gap and starts pointing at a history.

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