Decision Log

The record of why code exists — the decisions made during implementation, captured as first-class artifacts instead of left implicit in diffs. A diff shows what changed; the reasoning behind it (from both humans and coding agents) is normally lost. A decision log recovers it: on each commit it extracts decisions from code diffs and agent traces, dedupes them, presents them to a human to approve, then folds the approved ones back into the spec (the Spec-Driven Development sync mechanism, as implemented by Drew Breunig's Plumb). Reframed, it is a code review that captures intent — "these are the decisions that were made; is this right?" — rather than one that only checks lines. Crucially, even sloppy or hacky decisions get logged, never silently dropped, so the log stays a complete answer to "why does this code exist?"

Claims

Capture the decisions behind a change, not just the diff — the decision log is what answers "why does this code exist?" principle — durable: intent is not recoverable from a diff alone, and intent is precisely what future readers (human or agent) need; a system that records only what changed loses the why permanently.
Log even bad or sloppy decisions — never silently drop them. principle — durable: the log's value is completeness; the decision omitted because it was a hack is exactly the one you will later wish you had recorded (the same "held, never dropped" discipline the firehose engine runs on).
Extract decisions from code diffs and agent traces, dedupe, present to a human to approve, then update the spec. best practice — context: the Plumb per-commit workflow for keeping a spec authoritative under agent-generated change; it also reports spec-to-test and spec-to-code coverage.
Making implicit agent decisions explicit surfaces weird, silent LLM behaviors you would otherwise miss. observation — a supervision benefit: the approval step is where quietly-wrong agent choices become visible.
Decision identification and dedup are fuzzy and locally specific — treat the log as assistive, not authoritative. best practice — context: honest limitation of the approach; dedup "isn't perfect," identification is "likely locally specific," so the human approval gate is load-bearing rather than optional.

AI Second Brain — a personal-knowledge use of the same artifact: a decisions/log.md the agent appends dated decisions to on every big change (the level-1 second-brain layout).
Context Routing — the routing file points the agent at the decision log so it's found again.
Spec-Driven Development — the decision log is how the SDD triangle is kept in sync: intent extracted from new work flows back into the spec.
Agent Supervision — presenting deduped decisions to approve/reject is attention-routed, legible review; the log is the operator's record of what the fleet decided and why.
Error Analysis — surfacing "weird, silent LLM behaviors" from agent traces is the same read-the-traces reflex, aimed at intent drift rather than a failure taxonomy.
Self-Improving System — the auto-approve bucket writes silently to a change-log.md, a decision log of what the system changed on its own.
Distillate: Learnings from a No-Code Library: Keeping the Spec-Driven Development Triangle in Sync
Distillate: Every Level of a Claude Second Brain Explained
Distillate: How to Build a Self-Improving System with Claude Code — change-log.md as the record of auto-applied self-improvements.

Decision Log

Claims

Related

Linked from