Keep a decision log useful after the decision changes

Preserve the reason somebody might need again.

A decision log becomes difficult to use when the latest entry quietly replaces the old explanation. The next engineer sees the new choice but cannot tell what changed, which earlier constraint survived, or why the former approach was reasonable. Keep that history inspectable when you change the decision.

AWS’s architectural decision record process preserves accepted records and uses a newly accepted record to supersede an earlier decision. It also distinguishes Proposed, Accepted, Rejected, and Superseded states. The method below adds a small operational index to that lifecycle; the index and rollout fields are suggestions for your team, rather than an AWS requirement.

You can do this with ordinary repository files and review history. A separate context service is unnecessary when the team can find the applicable record and check its sources with the tools it already uses.

Separate acceptance from implementation.

Ask two questions: what design has the team accepted, and what behavior is deployed in the scope of this task? Those answers can differ during a migration. A design approval establishes an intended contract. It does not establish that every caller has adopted it.

Keep the accepted body of the old record unchanged. Add traceable status metadata or an index entry linking to the successor, rather than rewriting the original reasoning. Use a reviewed change for the status update. Keep proposed successors visible without presenting them as active replacements.

Follow a fictional change without rewriting its past.

Consider a fictional orders service. Decision D12 chose a synchronous result for order creation. Its reason was that the first caller needed a final order identifier before continuing. The service must still recover the same accepted order when that caller retries with the same request ID.

A later proposal, D31, introduces an asynchronous acknowledgement for a new API version. The proposal alone does not change D12. After review, the team accepts D31 for version two while retaining version one’s contract for existing callers. Stable request-ID handling remains a shared requirement; asynchronous acknowledgement does not settle every retry or concurrency question.

The log should show what D31 replaces and what it leaves intact. If the successor only changes version two, keep version one’s applicability explicit. If the team later retires version one, record that separate adoption decision and its evidence. Avoid marking the entire predecessor irrelevant merely because one scope changed.

Keep a dated index beside the accepted records.

The index is a navigation aid, with links to authoritative evidence. Give it an owner and an update trigger: acceptance, scope change, verified rollout, or a contradiction found during a task. Its “checked” date records when somebody inspected the sources; it is not a claim that nothing has changed since.

This fictional entry shows the minimum useful distinction. Replace the example identifiers and dates with your own evidence. If a fact cannot be established, write unknown and name the person or check that can resolve it.

Decision index — fictional example
Checked: 2 November 2026; owner: orders maintainer
D12: accepted 3 May 2026; synchronous result; source: D12 review
Applies: existing version-one callers
D31: accepted 1 November 2026; async acknowledgement; source: D31 review
Reason: new version-two caller accepts delayed completion
Consequence: caller must recover the eventual result
Supersedes: D12 result contract for version two only
Preserved: retry with the same request ID recovers the accepted order
Observed rollout: version-two sandbox only; production unknown
Before production: verify acknowledgement/recovery contract and caller handling
Next trigger: production rollout or a change to either API contract

Make the next task check the right scope.

For a change to a version-one caller, supply D12’s applicable contract and explain why D31 does not authorize changing that caller yet. For version two, supply D31’s accepted choice, the preserved retry requirement, and the unverified rollout boundary. Link both records so the reviewer can challenge the interpretation.

When code disagrees with the accepted design, record the disagreement instead of editing history to match code. It may be an incomplete migration, an implementation defect, or an undocumented decision. Ask the accountable owner which account applies before making a consequential change.

After implementation, update only facts you observed. A passing sandbox test supports that scenario. It does not prove a production cutover or every caller’s behavior. Keep the evidence and remaining scope separate.

Try this on one changed decision.

Choose one service and one decision that changed recently. Ask an engineer who missed the original discussion to identify the predecessor, the accepted successor, the scope that still uses the former contract, and one unresolved question. Let them use the log without an explanatory meeting first.

Record where they needed outside help, which links were missing, and how long the maintainer spent fixing the index. Stop or narrow the exercise if maintaining it costs more effort than the next task can use. Keep existing approval and test requirements.

A team lead can own this small trial with the service maintainer, using permitted repository records only. Compare clarification and preparation effort across a few similar tasks, while recording task differences. Better navigation is an observable result; faster delivery or fewer defects needs separate evidence.