A team writes decision records that nobody reads and that do not help when the decision is revisited years later. What is missing?

What is missing

The two fields that make a record useful later: the options rejected, and the conditions for revisiting.

Most decision records contain context, the decision, and consequences. That records what was decided and still leaves the future reader with bad options — leave it alone out of superstition, or change it and discover why it existed.

The fields that matter

1. Options considered and why each was rejected. This is the highest-value content. If an option was evaluated and rejected for a reason that still holds, re-proposing it wastes a quarter. If it was rejected for a reason that has expired, that is the trigger to revisit.

2. The conditions under which this should be revisited. The most-omitted and most valuable field:

Revisit when: the largest tenant exceeds one partition's practical limit, or cross-tenant analytical queries exceed 20% of load.

That clause turns an archaeological artefact into a live decision with a trigger someone can check. Without it, every inherited decision is permanent by default.

3. The constraints that forced the decision, including ones that were true then and may not be now — a platform limitation, a team's expertise, a deadline, a version that no longer ships.

4. What was explicitly not decided, so the next person knows which questions remain open rather than assuming they were settled.

Why nobody reads them

Usually because they are written as records rather than as arguments, and because they are not where the reader is. Two practical fixes:

• Write the decision as a short argument someone would actually read: what we are doing, why, what we gave up, and when to reconsider. One page.
• Keep them with the code and link them from the affected components, so the person changing the thing encounters the reasoning at the moment they need it.

The test

Give a record to someone who was not there and ask what they would do if they wanted to change the decision. If they cannot tell what would justify a change, the record documents an outcome rather than a decision — and the most expensive documentation failure is a correct document describing a world that no longer exists.