Decision speed is inversely proportional to the cost of rollback. Picking a logging library is a two-way door, settled in an hour. Picking a storage format, partitioning or ID scheme is a one-way door and requires an ADR.
The door metaphor is from Jeff Bezos’s 2015 letter to Amazon shareholders: Type 1 decisions are consequential and irreversible or nearly so, and deserve to be made slowly and carefully; Type 2 decisions are changeable, and should be made quickly by individuals or small teams. His warning runs both ways — an organization that grows tends to apply the heavyweight Type 1 process to everything, and becomes slow. The written record for the Type 1 ones is the Architecture Decision Record, proposed by Michael Nygard in “Documenting Architecture Decisions” (2011): a short file with context, decision, status and consequences, kept in the repository next to the code it constrains.
# ADR-014: Partition key for the orders topic
Status: accepted Date: 2026-03-02
Context: repartitioning a Kafka topic in prod = consumer downtime
+ rebuilding Flink state stores
Decision: partition by customer_id, not by order_id
Consequences: hot keys for large B2B customers;
mitigated with salted keys at >5% skewWhy the partition key is a one-way door: the key decides ordering guarantees and which consumer instance holds which state (92). Changing it means a new topic, dual writes or a replay (80), and rebuilding every stateful consumer — weeks, not a config change. The same holds for a primary-key scheme exposed in URLs, a public API field’s meaning (16), and anything written to long-lived storage in a format other systems read.
Turn one-way doors into two-way ones where you can. Expand–migrate–contract (17), a facade in front of storage, feature flags and versioned formats all lower the cost of rollback, and with it the process the decision needs. The misuse is the reverse: writing ADRs for library choices, which buries the few irreversible decisions among many reversible ones.