Architecture decision records, and why they stop being written

An architecture decision record is a short document describing a single significant technical choice: what was decided, what the alternatives were, and why the chosen option won. The idea was popularised by Michael Nygard in 2011, and the appeal is obvious to anyone who has spent a week reverse-engineering the reasoning behind a database choice made two years ago by someone who has since left.

What belongs in one

Formats vary, but the useful ones converge on a handful of fields. Anything beyond these tends to be ceremony that makes the record less likely to be written.

• Title — the decision, stated as a decision. "Use Postgres for the primary store", not "Database".
• Status — proposed, accepted, or superseded, with a link to whatever superseded it.
• Context — the situation that forced a choice. This is the field future readers actually need.
• Decision — what was chosen, in one or two sentences.
• Alternatives — the options rejected, and the specific reason each lost. Without this, the record cannot answer "did you consider X?"
• Consequences — what this makes easier, and what it makes harder or more expensive later.

The failure mode

Almost every team that adopts ADRs writes a strong first batch. Six months later the directory has eleven records and the last one is from March. This is not a discipline problem. It is that writing an ADR is a separate task from making the decision, and it happens after the interesting part is over — the argument has been had, in a pull request or a Slack thread, and everyone has moved on.

The reasoning was captured. It is just sitting in a thread nobody will find again. The gap is not between deciding and documenting; it is between documenting and being able to retrieve what was documented.

The second problem: records go stale silently

Even a well-maintained ADR describes a decision made under conditions that were true at the time. “We chose this because we expect under 10,000 users this year” is sound reasoning right up until the tenth month, when it quietly stops being true. Nothing in the document changes. Nobody is told. The decision simply becomes wrong while continuing to look authoritative.

This is why a decision record is more useful when the assumptions it rests on are tracked as first-class things rather than buried in prose — something that can be checked and can raise a flag when it no longer holds.

Where Ecko fits

Ecko reads the PR comments and Slack threads your team already writes and extracts the decisions from them, with the reasoning and rejected alternatives attached. The record gets written because the discussion happened, not because someone remembered to open a template. It then tracks the assumptions underneath each decision and tells you when one stops holding.