A technical decision can be sensible when you make it and expensive when you keep it. The workload grows. A supplier changes its pricing. A service acquires a different availability requirement. The engineers who remember the original tradeoff move to other teams, and “we chose this deliberately” slowly becomes “this is how the system works.”
A decision record preserves the reasoning. A revisit trigger makes that reasoning operational. It names the evidence or event that should cause someone to ask whether the accepted choice still fits. Without that condition, the record can become a beautifully documented permission slip for doing nothing.
The goal is not to reopen every architecture discussion every quarter. It is to distinguish a changed assumption from a familiar argument, and give the changed assumption an owner who can act on it.
Preserve the decision before adding the review mechanism
An architecture decision record, or ADR, should explain the context, the choice, and its consequences. AWS's ADR process guidance describes accepted records as immutable: a subsequently accepted decision supersedes the earlier record rather than rewriting its original reasoning. It also calls for an identified owner.
That is a useful baseline. Keep the original choice readable, including the drawbacks the team knowingly accepted. Put later observations in linked review notes or issues. If the choice changes, create a successor record and connect the two. An accepted record can gain a supersession pointer without losing the historical explanation of why it was accepted.
My recommended addition is a small review contract: assumptions, observable conditions, an evidence source, an accountable role, and the next action. These are operating choices for your team, not a claim that every ADR standard requires identical fields.
When Should a Staff Engineer Escalate a Technical Decision? covers a different question: who can make the choice when the working group lacks authority. Here, the initial choice has already been accepted. We are deciding when its assumptions deserve another look.
Start with the assumption that could become false
“Review this next year” is a calendar entry. “Review this if the data-residency requirement changes” is a reason. You often need both, but the reason should come first.
Pick the assumptions that materially separated the chosen option from the alternatives. A small service might tolerate manual recovery because failures are infrequent and recovery is brief. A shared platform might accept a commercial dependency because the vendor's support removes a burden the team cannot fund internally. A deployment design might rely on one region because the product has no requirement to survive a regional failure.
Useful assumption categories include:
- Scale: volume, concurrency, dataset size, or tenant count.
- Economics: operating cost, licensing model, or required support effort.
- Reliability: recovery time, incident frequency, or customer impact.
- Constraints: security policy, contract terms, residency, or retention.
- Ownership: the funded team and skills required to keep the system usable.
Do not turn every sentence into an alert. Select the few assumptions whose failure would plausibly change the decision. A record with twenty unowned conditions is less useful than one with two conditions someone actually checks.
Make a trigger observable and proportionate
A quantitative trigger needs a unit, a scope, an observation window, and somewhere to find the evidence. “Latency gets bad” leaves the difficult part to the next engineer. “The queue's oldest eligible job exceeds the product's processing target during normal operation for three consecutive business days” is something a team can investigate.
Define exclusions carefully. A backfill may be acceptable outside the ordinary processing target. Excluding all incidents, however, could erase exactly the evidence that matters. Record which workload the condition covers and why.
An event trigger can be simpler: a supplier announces end of support, a new contract introduces a recovery obligation, or the current owning team is dissolved. You do not need a synthetic numeric score for an event that already changes the operating constraints.
| Weak condition | More useful review condition |
|---|---|
| Revisit when costs rise | Review when the monthly bill exceeds the agreed budget for two billing periods; link the cost report |
| Revisit if customers complain | Review when confirmed failures breach the named product requirement; identify the incident evidence |
| Revisit when the team grows | Review before adding a second independent owning team that needs different release permissions |
| Revisit next quarter | Check next quarter whether the named assumptions still hold, even if no event has fired |
The observation window is a tradeoff. Too short, and you convert noise into meetings. Too long, and you normalize a deteriorating system. Choose it according to the cost of being wrong and the time needed to respond.
A reusable record addition
The following is a hypothetical example for a background-processing service. Its numbers are illustrative, not recommended defaults for production systems.
Decision: Keep jobs in the existing database-backed queue.
Status: Accepted
Reason:
Current throughput and recovery requirements fit the existing design.
A separate broker would add an operational dependency and migration work.
Assumptions:
- Normal traffic stays within measured queue capacity.
- The owning team can recover a stalled worker within the product target.
- Processing does not require cross-region failover.
Revisit triggers:
- Oldest eligible job exceeds 5 minutes on 3 consecutive business days,
excluding explicitly scheduled backfills.
- Queue maintenance exceeds 8 engineer-hours/month for 2 months.
- Product approves a cross-region recovery requirement.
Evidence:
Queue-age dashboard, maintenance log, approved requirement record.
Accountable role:
Background-processing service owner; named delegate in team directory.
Action:
Open a review issue within 5 business days. Summarize the changed
assumption and compare repair, capacity adjustment, and broker adoption.
An urgent reliability incident follows incident procedures immediately.
Calendar backstop:
Check assumptions at the next quarterly service review.
This block is deliberately small. Put detailed benchmarks and alternative designs elsewhere and link them. The record should make it easy to find the next decision, not become the entire architecture repository.
Work through the trigger without preselecting the answer
Suppose the hypothetical queue-age condition fires. The owner opens a review and discovers that one new tenant creates bursts that saturate a worker pool. The database itself still has spare capacity. A broker would change how work is distributed, but it would not automatically make the slow jobs faster.
The review should compare at least three plausible responses: adjust worker allocation, isolate the bursty tenant, or change the queue architecture. Gather enough evidence to separate them. A bounded load test might show that fair scheduling resolves the delay while preserving the existing design.
In that case, keep the accepted architecture decision and link a review note explaining what happened. Record the evidence, the mitigation, and whether the original trigger still makes sense. A trigger doing its job does not require a migration to justify the review.
Now change the hypothetical: product approves regional failover, and the current queue cannot satisfy the required recovery behavior. That is a different assumption failure. The team needs an architectural comparison that includes recovery semantics, data consistency, operational ownership, and migration risk. Raising worker count does not answer it.
The trigger should start the investigation. It should never smuggle in “replace this with my preferred system.”
Give the review an owner and an outcome
Assign accountability to an operating role that survives a personnel change. A named person helps today; a service owner or platform owner makes the responsibility discoverable next year. When ownership transfers, include important decisions and their active review conditions in the handoff.
A review should end with one of four outcomes:
- Keep the choice: the assumption still holds or the alternatives remain worse.
- Mitigate within the choice: a limited change restores the intended operating range.
- Gather bounded evidence: name the experiment, owner, and deadline.
- Propose a replacement: create a successor decision with migration and ownership consequences.
For the replacement outcome, identify capacity explicitly. A Technical Strategy Needs an Explicit Stop-Doing List explains why a direction without released capacity is incomplete. “We should migrate” is not an executable commitment.
Use staff-level status writing to communicate the changed assumption, next decision, and remaining risk. Reporting that a review meeting occurred tells readers very little.
Keep the maintenance cheaper than the uncertainty
Avoid building a custom registry before proving that a few records and linked issues work. Start with consequential decisions already close to a boundary. Connect triggers to dashboards and operating reviews people use today. An alert nobody receives and a quarterly check nobody owns are the same failure with different formatting.
Also avoid using the review date as an expiration date. A stable design does not become wrong because ninety days passed. The calendar backstop exists to catch unobserved changes, stale ownership, and missing evidence. It should be a short assumption check when nothing meaningful has changed.
A good technical decision record explains why yesterday's choice made sense. A useful revisit trigger gives tomorrow's owner a fair chance to notice when that explanation stops fitting. Write the condition while the tradeoff is fresh, make the evidence findable, and leave room for the review to conclude that the original decision is still right.
For more practical engineering systems and leadership guidance, visit Slaptijack.
