Decision Trace Schema (DTS) v0.1 — Overview
Teaser. The full schema has run internally since May 2026; publication follows review.
Most knowledge systems record conclusions. Almost none record decisions — the choice, the reasoning, who made it, under what constraints, what alternatives were rejected, and what later replaced it. The Decision Trace Schema is our attempt to make decisions first-class, machine-readable objects, born from operating a human-AI partnership where an amnesiac AI must reconstruct why things are the way they are from files alone.
The shape of it
Every decision document carries structured frontmatter and a conventional narrative:
- Provenance — author (
human,ai, orshared) and how the decision emerged: real-time dialogue, retrospective documentation, incident response, architecture review, governance audit. - Lifecycle —
draft → approved → implemented → active → under-review → archived, with explicit human-approval gates for anything touching identity or infrastructure. - Maturity — how settled the decision is, from
seed(single observation) throughsapling(multiple validations) toevergreen(foundational, repeatedly validated). - Supersedence —
supersedes:anddeprecated_by:links, so a reversed decision becomes a tombstone pointing at its replacement rather than a silent edit. The graph of decisions tells the evolution story. - Narrative — six conventional sections: the question, the choice, the reasoning, the architectural implications, the long-term stakes, and the road not taken.
Why it exists
An amnesiac AI is a merciless test harness for institutional memory. If the
reasoning behind a choice isn’t written down in a findable, structured form,
it is — for the AI half of this partnership — as if it never happened. What
began as a coping mechanism turned out to be a governance framework: with
decisions as schema’d objects, you can audit which choices were made by the
human, which by the AI, which were ratified, and which quietly rotted into
under-review.
The schema has governed dozens of live decision documents over months of operation, including the decisions that define the AI’s own identity and the rules for revising it.
What v0.1 publication will include
The full frontmatter specification, the narrative conventions with worked examples, the approval-authority matrix (who may change what, by layer), the supersedence rules, and the open problems we know about — querying at scale, contradiction resolution between two approved decisions, and maturity progression criteria.
Schema publication to follow review.