Make a technical decision people can revisit

Describe the observed problem and what would count as improvement. “The checkout service cannot recover from a provider timeout without duplicate work” is more actionable than “we need event-driven architecture.” Record scale, failure tolerance, delivery constraints, and what the team can operate. Distinguish measured conditions from predictions.

Include the option of improving the current design. A rewrite or service extraction should compete with a smaller change that addresses the same constraint. If the new option solves a different problem, make that explicit rather than giving it credit for benefits the current business does not need.

For each credible option, explain data ownership, interfaces, deployment, failure behavior, observability, access control, and recovery. A service boundary adds an operational relationship: callers need to handle latency and failure, teams need to version contracts, and somebody needs to be available when it stops working.

Evaluate the ordinary path and the bad day. What happens when a dependency is slow, a message is delivered twice, a deployment is partial, or the person who understands the system is unavailable? A prototype can answer a narrow technical question, but it does not establish that the full operating model is affordable or maintainable.

State why your preferred option could be wrong. This lets reviewers correct a mistaken priority before spending their time on implementation details. Ask stakeholders whether the proposed cost, delay, and failure modes are acceptable. Invite alternatives that meet the same constraints rather than defending a particular tool as an identity.

Keep a decision owner and a time boundary for review. Consensus may be valuable, but unresolved ownership can make a review endless. Record material disagreement in the decision itself. Future engineers should be able to see which risks were understood and consciously accepted rather than assuming the original team overlooked them.

A final-state diagram is only part of the decision. Explain how you reach it safely, how mixed versions behave, how you verify progress, and when temporary compatibility paths will be removed. Migration work includes data correction, operational training, and changes to downstream consumers, not just the new service.

Define the evidence that would make you reconsider. It might be a new load profile, a change in ownership, an operating cost that exceeds the agreed boundary, or a product requirement the original design excluded. A decision record should preserve context without making yesterday’s assumptions permanent.