A database platform team is asked why a decade-old partitioning scheme was chosen. Nobody remembers, the original architects have left, and the only artefact is a diagram with no rationale. What failed here, and what document would have prevented it?

What failed

Not the absence of documentation — there was a diagram. What failed is that the diagram records structure and the question being asked is about rationale. Those are different documents, and only one of them ages well.

A diagram tells you what is. It cannot tell you what was considered and rejected, what constraint forced the choice, or whether that constraint still exists. Without rationale, every inherited decision presents the team with the same bad options: leave it alone out of superstition, or change it and discover why it was there.

The concrete cost

For a partitioning scheme specifically, the cost is severe. The team cannot answer:

• Was the partition key chosen for query locality, for maintenance windows, for regulatory data separation, or because of a limitation in a version that no longer ships?
• Which access patterns were assumed? Are they still the access patterns?
• What was tried and rejected? If hash partitioning was evaluated and rejected for a reason that still holds, re-proposing it wastes a quarter.

So the scheme becomes untouchable. Untouchable decisions accumulate, and eventually the architecture is a museum.

The document that would have prevented it

An Architecture Decision Record: context, the options considered, the decision, the consequences, and — the field most often omitted and most valuable — the conditions under which this should be revisited.

Context: partition by tenant_id because 95% of queries filter on it and
         regulatory separation is required per tenant.
Rejected: hash partitioning (breaks tenant-level export and legal hold),
          date partitioning (does not match the dominant access pattern).
Revisit when: the largest tenant exceeds a single partition's practical
              limit, or cross-tenant analytical queries exceed 20% of load.

That last clause is what turns an archaeological artefact into a live decision. It converts "nobody remembers why" into "here is the trigger, and here is whether it has fired".

The generalisable lesson

Document decisions, not structures. Structures are recoverable from the system; rationale is not. And write the expiry condition, because the most expensive documentation failure is not a missing document — it is a correct document describing a world that no longer exists.