Decision Triggers
Know the events that should trigger an architecture decision vs. just a task.
Why
Not every choice is an architecture decision — 'which linter' is a task, 'which database' is a decision. Treating tasks as decisions (over-process) slows the team; treating decisions as tasks (under-process) means the DB choice gets made by whoever picks up the ticket, with no record of why. Decision triggers are the events that should escalate to a formal decision: a new external dependency, a cross-team interface, a choice that's expensive to reverse. Defining them upfront means the right decisions get the right process, automatically.
When
Define once, apply continuously. Takes 2 hours to define the trigger list. Revisit quarterly.
How
1. List the events that should trigger a formal decision (ADR + review): - Adding a new external dependency (DB, queue, framework, SaaS) - A choice that's expensive to reverse (> 1 eng-week to change) - A cross-team interface (API contract, data format, event schema) - A choice that affects on-call (new tech to operate) - A choice that affects cost > $1k/mo 2. List events that are NOT decisions (just tasks): - Internal refactors, linter config, test framework, internal naming 3. When a trigger fires, the work pauses until an ADR is written + reviewed 4. Make the trigger list visible (in CONTRIBUTING.md) so everyone knows the bar 5. Audit monthly: were decisions made without ADRs? Add a trigger if so
Example
Trigger list (in CONTRIBUTING.md): - New DB/cache/queue → ADR required - New framework or major lib (>1000 stars, becomes a dependency) → ADR - API contract change that breaks consumers → ADR + consumer review - Anything that adds a new on-call skill → ADR + on-call sign-off - Cost impact > $1k/mo → ADR + finance review NOT a decision (just a PR): - Internal rename, linter rule, test util, refactor within a service Audit: last month, "added Redis" had no ADR → added "new datastore" trigger.
Common Problems
- ⚠Treating every choice as a decision — the team drowns in ADRs for linter configs and stops writing them for the things that matter.
Best Practices
- ✓Keep the trigger list short (5-7 items) — too many triggers and people route around the process; too few and decisions get made by accident.
- ✓Review the trigger list when a decision was made without an ADR — the gap is usually a missing trigger, not a process violation.