Tech debt is a list of decisions nobody wrote down
The quarterly debt review is a team staring at a spreadsheet of its own past. Row 14 reads "auth service still queries the billing DB directly". Someone wants it fixed this quarter. Someone else half-remembers that it was deliberate, a bridge built during the payments migration, with a condition attached about when it could go. Nobody can produce the condition. So row 14 survives another quarter, because nobody repays a loan without reading the terms, and the terms were never written down.
Most tech debt registers look like this. They are inventories of code that looks wrong today, detached from the decisions that made it look right once. The debt metaphor is about borrowing, and every real loan has terms: what was traded, what it bought, when repayment was supposed to happen. Lose the terms and rational repayment becomes impossible. The team either "fixes" a trade-off that is still earning its keep, or keeps paying interest on a genuine shortcut because touching unexplained code feels like defusing something. AI dev teams feel this sharpest, since an agent told to clean up debt will cheerfully refactor a constraint it has no way to see.
Our answer was to record the decision in the same session that takes the shortcut. kgai, the MIT-licensed tool we build, keeps an append-only, immutable decision log per project. Capture happens at the write boundary, through a skill and hooks in the Claude Code plugin, with a standalone kg CLI for questions from any terminal. There is no daemon and no server to run.
The graph an agent queries is a deterministic projection of that log. Recall is lexical matching plus graph traversal, with no embeddings in the read path, and it returns only decisions in force, so a debt item comes back with its living rationale rather than every stale opinion ever attached to it. Repaying the debt is itself a decision, one that supersedes the shortcut through an explicit link with a reason, the pattern we unpack in repealing a rule needs a record. The abandoned alternatives stay queryable too, because dead ends are documentation, and half of a debt register is paths the team already knows not to walk.
For a team, sync is opt-in through an S3 bucket you own. Each writer appends to a shard of their own, so parallel writes never cause a textual conflict. The store holds up: 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 than that.
Your register names the debt. The log holds the terms. With both, repayment becomes a decision instead of a gamble.
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.