Decision Trace: What to Record Before the Reasoning Disappears

The architecture diagram shows a queue between two services. The repository shows when it was introduced. The meeting transcript contains an hour of discussion. None of those artifacts necessarily tells a new engineer why the queue was chosen, what tradeoff was accepted, or which change would make the choice worth revisiting.

A Decision Trace keeps that reasoning connected to the decision and the work it informs. It is a record that people can inspect and challenge. Its value depends on the quality of its evidence and review, as well as the presence of its fields.

Consider an illustrative choice: a customer update must reach a downstream reporting service. The team has to decide whether the customer-facing request should wait for that service to respond.

Record what is known, and where it came from

The team observes that the reporting service has scheduled maintenance periods. The source is its operating documentation. A product owner confirms that customers must be able to submit updates during those periods. An integration owner confirms that delayed reporting updates can be accepted if their status remains visible.

Those statements have different sources and should remain distinguishable. If the integration owner has not confirmed the last point, it is an open question, not an observation. A plausible statement generated during design becomes useful evidence only when its basis can be checked.

The trace should let a reviewer move from the statement to that basis. This keeps a decision from acquiring false authority merely because it has been repeated in several documents.

Name the constraints that decide between options

In this example, the customer-facing service must remain usable during reporting maintenance. Accepted updates must not disappear. Repeated delivery must not create duplicate records. The service team needs a way to identify and recover failed updates.

These constraints make the comparison meaningful. Without them, “use a queue” can sound like a preference for a technology. With them, the team can examine whether the proposed design solves the actual problem.

Constraints also have scope. An operating requirement for this workflow should not quietly become an enterprise-wide rule. Record where it applies and who can interpret or change it.

Keep the alternatives and their consequences

The team considers two options. A synchronous call provides a simple immediate response when both services are available, but couples customer acceptance to reporting availability. Asynchronous delivery separates those events, but requires pending states, duplicate handling, and recovery ownership.

Both options deserve an honest account. The selected option does not become stronger because the rejected one is described unfairly. A useful comparison explains where each fits and what additional work each creates.

The team selects asynchronous delivery. Its rationale links the availability constraint to the chosen design, and acknowledges the recovery responsibilities that follow. Those responsibilities become part of the architecture and delivery plan rather than a footnote to the decision.

Make approval and open conditions visible

The architecture reviewer approves the proposed interaction. The service owner accepts responsibility for recovery, subject to reviewing the operating procedure before release. The decision is therefore specific: the architecture can proceed, and the release still depends on an identified condition.

Recording that distinction prevents a familiar misunderstanding. A later reader should not have to infer whether “approved” meant the diagram, the implementation, or permission to expose the workflow to users.

When new evidence arrives, preserve the relationship between the earlier choice and the revision. A decision record is useful precisely because it allows a team to understand change; it should not force the team to pretend that an earlier assumption remains true.

A whole record still needs effective review

Required fields can expose omissions. They cannot establish that the options were sensible, the source was correct, or the most important failure case was considered. A record with every field populated can still contain weak reasoning.

The practical review question is whether the rationale follows from the evidence and constraints. Ask what would change the decision. In this case, a new requirement for immediate reporting consistency would reopen the tradeoff. A reviewer should be able to identify that relationship without reconstructing the entire discussion.

Archangel's Decision Trace connects observations, constraints, options, rationale, sources, and downstream artifacts around architecture decisions. Review pathways keep reviewer action connected to the work. The technology overview explains how that record fits with explicit verification and governance.

Start with a consequential choice in a project your team already knows. Record why it was made, what evidence supports it, and what would reopen it. Then hand the record to someone who was not in the room. The questions they still have are the most useful test of what to capture next.