Who objected. Who decided.
AI Decision Records: one markdown file per consequential decision made with AI agents. Independent positions, preserved dissent, human arbitration.
Multi-model tools increasingly show you where models disagree, then the disagreement evaporates into a chat answer. Execution logs tell you what ran. Neither answers the audit question that matters for high-consequence work: who objected before we acted, and who decided. AIDR makes that answer a plain file in your repo.
Why a file, not a chat log?
Multi-model tools increasingly show you where models disagree, then the disagreement evaporates into a chat answer. Execution logs tell you what ran, not who objected or who had authority to decide. AIDR makes that answer a plain file in your repo, checkable by anyone from the file alone.
Independent positions
Each participant records a position before seeing the others, labeled by provider. A record claiming independent multi-model review needs at least two distinct providers.
Dissent preserved
An oppose or alternative stance, or a named objection, is never deleted. Records are superseded, not rewritten.
Human arbitration
A human, never a model, authors the Arbitration section and addresses every objection: accepted, rejected with reason, or deferred.
| Claim | Requirement |
|---|---|
independent-positions | Two or more positions with distinct provider values, recorded before arbitration |
dissent-preserved | An oppose/alternative position or objection exists, and the arbitration addresses it |
human-arbitrated | status is arbitrated and the Arbitration section is complete |
The linter checks structural prerequisites and declared providers. Actual independence, identity and the adequacy of arbitration require review of the record and supporting evidence.
Record anatomy
| Section | Purpose |
|---|---|
| Context | Why this decision exists and what's at stake |
| Question | The single decidable question being answered |
| Positions | One subsection per participant: agent, model, provider, stance, summary |
| Objections | Named failure modes or risks raised against a position |
| Arbitration | The human decision, addressing every objection |
| Evidence | Links to supporting material (optional) |
Quick start
No runtime, no service, no protocol to learn. Copy the template, fill it in when a decision matters.
1. Get the template
Literal
git clone https://github.com/snapsynapse/aidr.git cd aidr
Every command below runs from that directory. Cloning is a convenience, not a requirement: the format needs one file, so downloading the template on its own works too. Only the optional linter needs the repository.
2. Copy the template
Replace: AIDR-NNNN-slug.md → an unused record filename.
Customize
cp -n templates/AIDR-0000-template.md \ decisions/AIDR-NNNN-slug.md
Set the id to match the filename prefix. Fill in title, date and human arbiter; start with status open and omit decided. Replace template placeholders with real positions and objections, leaving Arbitration empty until the human decides. Preserve all actual recorded dissent.
3. Record positions
### Position: claude - agent: claude - model: claude-sonnet-5 - provider: anthropic - stance: recommend - summary: one sentence
4. Arbitrate
## Arbitration - decided_by: sam - date: 2026-07-02 - decision: one sentence Prose addressing every objection.
No tooling needed
# Optional: verify conformance node tools/aidr-lint.mjs decisions/
The reference linter is zero-dependency and optional. A conforming record is defined by the specification, not by any tool.
Turnfile is the advanced profile
AIDR re-expresses Turnfile's core concept, independent agent positions, preserved dissent, human arbitration, at the smallest possible unit of adoption: one markdown template. A team that outgrows single-decision records graduates to a full Turnfile session. Conceptual lineage is by citation, not shared code or shared history; this repo stays dependency-free and small.