technical-decision-making

Classify the decision as a one-way or two-way door first, then build a weighted decision matrix with criteria agreed before scoring. Score each option including the do-nothing incumbent, and treat results within 0.3 points as tied rather than a clear winner.

A two-way door is reversible in days to weeks, like a logging library or CI provider, and deserves hours of analysis. A one-way door, like a primary datastore or public API contract, is costly to reverse and warrants spikes, an ADR, and a named owner.

Define three things before writing code: the specific question, a time-box, and a decision rule with measurable thresholds. Record the result even when it changes nothing, and avoid spikes when the uncertainty is about preference rather than fact.

Write an ADR for one-way door decisions such as datastores, public APIs, or vendor choices, including alternatives considered, consequences, and recorded dissent. Two-way door decisions only need a PR description.

Common anti-patterns include reverse-fitting matrix weights to a preferred option, running unbounded spikes without decision rules, requiring consensus, and skipping revisit triggers. Fix weights before scoring and write falsifiers at decision time.