Decision Log¶
Register — instantiates Traceability Linking
Captures each significant decision as a linked record — its rationale, the alternatives weighed, who approved it, and the artifacts it affects — so a choice can later be traced back to why it was made and forward to what it touched.
Most systems remember what was decided but lose why. A Decision Log makes the decision itself a first-class traceable unit: each entry records the choice, the forces and evidence behind it, the alternatives rejected and the reason, who approved it, and — the move that turns it from a diary into traceability — links forward to the artifacts, services, or obligations the decision now governs. Its defining idea is rationale capture anchored to consequence: not the support relation between claims and evidence (that is a citation chain), and not the edit history of records over time (that is an audit trail), but the durable justification behind a choice, tied to what implements it. Six months on, "why is it built this way?" resolves in one hop instead of an archaeological dig.
Example¶
An engineering team is deciding whether to move service-to-service traffic from synchronous calls to an event queue. Rather than let the reasoning live in a chat thread, they open a log entry in the lightweight Architecture Decision Record (ADR) format[n1]: the context (calls fail in cascades under load), the decision (adopt async messaging for these three services), the alternatives weighed (bulkheads, retries with backoff) and why they were set aside, the approver, and links to the services affected and the tickets implementing it.
A year later a new hire asks why everything is asynchronous. The log answers in a sentence and points at the exact services. When a later decision reverses part of it, the original entry is not deleted — it is marked superseded-by the new one, so the chain of reasoning stays walkable in both directions.
How it works¶
Each entry couples a decision to its justification and to the things it governs. Three properties make it traceability rather than note-taking: entries are append-only and superseding (a reversal is a new entry that links back, never an edit that erases the old reasoning); every entry carries a rationale anchor — the forces, evidence, and approving authority behind the choice; and every entry carries forward links to the artifacts that implement or are bound by it. The forward link is the load-bearing part — without it, the log records opinions, not a navigable origin-to-implementation chain.
Tuning parameters¶
- Logging threshold — which decisions earn an entry. Log everything and the signal drowns; log only the "architecturally significant" and you miss the reversal that later bites. Set it to decisions that are costly to reverse or hard to reconstruct.
- Rationale depth — a one-line reason versus context-forces-alternatives. Deeper entries survive staff turnover better but cost time and tempt after-the-fact polishing.
- Forward-link discipline — whether entries must link to implementing artifacts. High discipline makes impact traceable; low discipline degrades the log into a diary.
- Supersession policy — how reversals are recorded (marked-superseded vs. silently replaced). Marking preserves the reasoning trail; replacing loses it.
- Ownership capture — whether each entry names an accountable approver, which determines whether the log can answer "who decided this?"
When it helps, and when it misleads¶
Its strength is preserving the rationale that evaporates the moment the deciders move on, and making reversals deliberate: you can see that a choice was made knowing the alternatives, and trace it to what it now governs. That is what lets a later team change a decision on purpose rather than by accident.
Its failure modes are human. Rationale can be sanitized — the political reason omitted, the real trade-off softened — so the log records a defensible story rather than the true one. Entries are easily written after the fact to manufacture a paper trail for a decision that was never really deliberated, which is the classic misuse: a log run backwards to justify rather than to record. And when forward links go unmaintained, the log becomes a graveyard of entries pointing at artifacts that no longer exist. The discipline that guards against this is to log at decision time, name the accountable approver, and keep the forward links live — a decision that isn't linked to what it governs isn't yet traceable.
How it implements the components¶
traceable_unit— each decision entry is the identifiable unit that links point to and reviewers inspect.source_reference— the rationale, forces, evidence, and approving authority anchor the decision to why it was made.impact_link— forward links tie the decision to the artifacts, services, and obligations it now governs.
It does not type links with fine-grained support semantics (link_semantics — that's Citation Chain), preserve the who-changed-what-when history of the links (audit_trail — Audit Trail Record), or define which decisions must be linked (coverage_rule — Traceability Dashboard).
Related¶
- Instantiates: Traceability Linking — the Decision Log supplies the decision-to-implementation strand of the trace network.
- Sibling mechanisms: Audit Trail Record · Change Impact Report · Citation Chain · Data Lineage Record · Requirements Traceability Matrix · Chain-of-Custody Record · Source Control Linkage · Test Coverage Link · Traceability Dashboard
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: Decision Log operates as a durable record, ledger, register, or trace whose value depends on preserving actual state or history because it captures each significant decision as a linked record — its rationale, the alternatives weighed, who approved it, and the artifacts it affects — so a choice can later be traced back to why it was made and forward to what it touched.
Independent corroboration: The frozen evidence defines Decision Log as 'Captures each significant decision as a linked record — its rationale, the alternatives weighed, who approved it, and the artifacts it affects — so a choice can later be traced back to why it was made and forward to what it touched', so its operative form is Record, Log & Register.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Software architecture cohered append-only architecture decision records capturing context, choice, rejected alternatives, consequences, and supersession links alongside the artifacts they govern.
Related originating lineages:
- Organizational & Management Science — Decision journals and governance registers provide a broader lineage for durable rationale and approval records.
Review resolution: Software architecture cohered append-only architecture decision records capturing context, choice, rejected alternatives, consequences, and supersession links alongside the artifacts they govern.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
A Decision Log records that a decision was made and why; it does not decide which record is authoritative when two conflict — that governance question belongs to Source-of-Truth Assignment, a separate archetype. And an entry with no forward link is not yet traceability: the link to what the decision governs is what distinguishes a log from a diary.
[n1] The Architecture Decision Record — a short, append-only entry capturing a decision's context, the choice, and its consequences — is an established lightweight practice popularized by Michael Nygard; superseded decisions are marked rather than deleted, preserving the reasoning trail. ↩