Decision

Origin & evolution

The modern discipline of recording decisions comes from Michael Nygard's 2011 essay Documenting Architecture Decisions. He proposed the Architecture Decision Record (ADR): a short document capturing one decision, its context, the choice made, and its consequences. The format barely changed in the decade since, and Martin Fowler later endorsed it as the standard way to give future maintainers the why behind a system, not only the what. Nygard's insight🔦InsightUser ResearchA synthesised finding from researchView reference → was that the act of writing clarifies the thinking, and the record outlives the people who made it.

Around the same time, Jeff Bezos gave the field a complementary lens. In his 2015 letter to Amazon shareholders he split decisions into two types. Type 1 decisions are one-way doors: consequential, hard or impossible to reverse, so they deserve slow and careful deliberation. Type 2 decisions are two-way doors: changeable, so they should be made fast, ideally by individuals or small groups. His warning was that organisations drift toward treating every Type 2 decision as Type 1 as they grow, which kills speed.

The two ideas answer different questions. Nygard tells you how to record a decision; Bezos tells you how much process a decision deserves before you make it. A mature team uses both: classify reversibility first, then write the record at a depth that matches the stakes. The live debate now centres on decay. ADRs rot when superseded decisions are not linked to the ones that replaced them. The record then becomes a graveyard, when its value depends on staying a connected chain of reasoning.

How it works in practice

A fintech team is choosing how to store ledger data. Postgres is familiar; a purpose-built ledger database promises stronger guarantees but locks them into a vendor. They classify it as a one-way door, because a ledger migration after launch would be ruinous, and spend two weeks on it. The decision record names the context (regulatory audit requirements, expected transaction volume of 4 million per day), the choice (Postgres with an append-only schema), the alternatives rejected, and one explicit consequence: they accept slower analytical queries and will revisit if read latency exceeds 200ms at scale. Eighteen months later a new engineer asks why they did not use the ledger database. The record answers in ninety seconds, and the argument does not reopen.

Decision vs. its neighbours

• Assumption🤔AssumptionStrategyA belief taken as true that underpins a strategyView reference → is a belief the team holds without proof, often unexamined. A decision is a commitment the team has actually made. Decisions frequently rest on assumptions, and surfacing the assumption is how you stress-test the decision before it hardens.
• Hypothesis🧪HypothesisValidationA testable belief about a solutionView reference → is a testable prediction awaiting evidence🔎EvidenceValidationData supporting or refuting a hypothesisView reference →; it is provisional by design. A decision closes the question and commits resources. A two-way-door decision can behave like a hypothesis, since you intend to reverse it if reality disagrees, but the team has still committed to act now.
• Constraint🔒ConstraintStrategyA constraint entityView reference → is a fixed boundary the team did not choose and cannot easily move, such as a budget cap or a regulation. A decision is a choice made within those boundaries. Confusing the two lets teams treat self-imposed habits as immovable law.

In the graph

In the Unified Product Graph, a decision sits in the strategy region as a first-class node that products and structures point back to. Strategic pillars🏛️Strategic PillarStrategyA foundational principle that guides decisionsView reference →, products, design systems🧰Design SystemDesign SystemThe root design system entityView reference →, and bounded contexts🔲Bounded ContextEngineeringA DDD bounded context defining a service boundaryView reference → all link through edges such as product_decided_via_decisionProductdecided viaDecisionhierarchy, strategic_pillar_decided_via_decisionStrategic Pillardecided viaDecisionhierarchy, design_system_decided_via_decisionDesign Systemdecided viaDecisionsemantic, and bounded_context_decided_via_decisionBounded Contextdecided viaDecisionhierarchy, so any artefact can be traced to the reasoning that shaped it. Evidence flows in through experiment_run_informed_decision_decisionExperiment Runinformed decisionDecisioncross-domain, closing the loop between what was tested and what was chosen. The cost side is explicit too: decision_incurs_technical_debt_itemDecisionincursTechnical Debt Itemcausal records the debt a choice knowingly took on, which turns the ADR's "consequences" field into a queryable liability rather than a forgotten footnote.