Framework knowledge decays quickly. Decision quality compounds.
An engineer who memorizes one queue, database, or cloud platform can move fast inside familiar boundaries. An architect who can expose constraints, identify invariants, compare failure modes, and design reversible experiments can make progress when the tools change.
That capability is built through a repeatable decision record—not through longer technology lists.
Use a compact decision model #
For consequential choices, capture seven fields:
- Outcome — what user or business result must improve?
- Constraints — latency, cost, regulation, team skill, deadline, and scale.
- Invariants — what must remain true during failure and change?
- Options — include the current design and doing less.
- Evidence — measurements, prototypes, incidents, and authoritative references.
- Reversibility — migration and exit cost.
- Review trigger — the condition that makes the decision stale.
# Decision: isolate analytics writes from checkout
Outcome: protect checkout p99 during reporting spikes.
Invariant: accepted orders remain durable and queryable.
Evidence: 38% of peak DB CPU is unbounded report scans.
Choice: CDC into a separate analytical store.
Guardrail: source lag < 5 minutes for operational reports.
Rollback: retain existing report endpoint behind a flag.
Review: when peak source CPU stays below 45% for 30 days.This is an architecture decision record (ADR) with operational teeth. The review trigger prevents a correct decision from becoming permanent folklore after its assumptions change.
Prefer invariants over products #
“Use Kafka” does not transfer across contexts. “A committed event must survive one broker loss, consumers may process it more than once, and effects must converge” is reusable.
“Use microservices” is similarly weak. “Deploy these capabilities independently because their change cadence and failure budget differ” exposes the reason and the cost.
Tool choices become easier after the system promise is explicit.
Grow judgment through prediction #
Before shipping a decision, write what you expect:
- which metric will move;
- which failure becomes more likely;
- where the new bottleneck will appear;
- what operators will see first;
- when the option stops being economical.
Review the prediction after an incident or one operating quarter. The delta between expected and observed behavior is the learning asset. Without the prediction, teams rewrite history and call every outcome inevitable.
Leadership application #
Decision records are not permission documents. Keep them short, discoverable, and close to the code or service they govern. Assign a directly responsible owner, invite dissent before commitment, and separate reversible choices from one-way migrations.
| Decision shape | Governance |
|---|---|
| reversible and low blast radius | owner decides; observe |
| reversible but expensive | written options and staged experiment |
| hard to reverse | multi-discipline review and migration rehearsal |
| safety or compliance boundary | independent evidence and approval |
An error-budget policy supplies another useful model: reliability is not “as much as possible.” It is a product commitment that should alter release behavior when consumed.
Common mistakes #
- Recording the chosen tool but not rejected alternatives.
- Inventing scale requirements with no workload evidence.
- Treating a benchmark as production behavior.
- Hiding organizational constraints as technical necessities.
- Never revisiting decisions after the triggering constraint disappears.
Trade-offs #
Writing decisions consumes time and can become ceremony. Record only choices with meaningful future cost, keep the format proportional to risk, and automate links from services to relevant records. The alternative—reconstructing intent during an incident or migration—is usually more expensive.
Durable expertise is a library of tested decision models. Tools are examples inside that library, not the library itself.