Decision Making & ADRs¶

Good decisions are fast, written, and reversible when possible.

This is not a statement about cutting corners. It's a recognition that in software, the cost of a wrong decision is usually much lower than the cost of delayed or unmade decisions—as long as you can reverse course when you learn more.

The problem is not that teams make bad decisions. The problem is that teams make slow decisions (analysis paralysis), unrecorded decisions (no one remembers why), or avoid decisions altogether (hoping the problem goes away).

This chapter provides a system for making decisions well: with appropriate speed, with clear accountability, and with a written record that serves future you and future team members.

The problem this solves¶

Most decision dysfunction falls into one of these categories:

Decisions take forever. The team wants consensus. Everyone wants more data. No one wants to be wrong. Meanwhile, work stalls waiting for a call that could have been made in a day.

Decisions have no owner. Someone said something in a meeting, and everyone assumed that was the decision. But no one wrote it down, no one owned it, and six weeks later, three people have three different memories of what was decided.

Decisions are relitigated constantly. A decision was made months ago, but someone new joins, disagrees, and the whole debate starts over because there's no record of the original reasoning.

Decisions aren't actually decisions. They're vague agreements to "look into it" or "think about it more." No clear choice, no owner, no timeline.

The system described here addresses all of these by introducing:

Clear roles (who drives, who decides, who contributes, who is informed)
A simple classification (reversible vs. irreversible, local vs. cross-team)
Time-boxed exploration (prevent analysis paralysis)
Written records (ADRs for big decisions, decision snippets for small ones)
Review dates (nothing is permanent; context changes)

When to use this approach¶

Use this system when:

A decision affects multiple people or has consequences that last beyond the current sprint.
You're choosing between meaningful alternatives (not just "do it" or "don't do it").
Someone is stuck waiting for a call to be made.
You've had the same debate more than once.

You don't need a formal process for:

Trivial decisions that affect only the person making them.
Decisions that are obviously reversible within hours.
Decisions that have a clear owner and no disagreement.

Roles: Driver, Decider, Contributors, Informed¶

Every decision needs clear roles. Ambiguity about who decides is the root of most decision paralysis.

Role	Responsibility
Driver (D)	Drafts the pre-read. Orchestrates input. Tracks to closure. Doesn't necessarily make the call.
Decider (A)	Accountable for the decision. Makes the final call. Usually an EM, TL, or designated lead.
Contributors (C)	Provide input—subject matter expertise, risk assessment, constraints. Platform, security, product, design.
Informed (I)	Affected by the outcome but don't need to participate in the decision. Notified after.

For small decisions, Driver and Decider can be the same person. Just make it explicit.

The DACI model

This is a simplified version of the DACI framework (Driver, Approver, Contributors, Informed). The key insight is the same: someone must own the process (Driver) and someone must be accountable for the call (Decider). Without both, decisions stall or fragment.

Classifying decisions¶

Not all decisions need the same treatment. The two dimensions that matter most are:

Reversibility: Can we undo this easily if we're wrong?
Blast radius: Does this affect just our team, or multiple teams/systems/users?

This creates a simple 2×2:

	Local (one team)	Cross-team / Org
Reversible	Decide in PR/issue. Capture a decision snippet.	One-screen pre-read + triad review. Capture snippet.
Irreversible	ADR-lite (≤1 page) with review date.	Full ADR. May need architecture forum review.

When to write an ADR¶

Write an ADR when any of the following is true:

The decision is irreversible for at least a quarter, or hard to undo once users/systems depend on it.
It affects interfaces between teams, data contracts, or security posture.
It's a policy or process change that affects how people work.
The cost of being wrong is high (significant rework, user harm, regulatory risk).
You've had this debate before and want it to be the last time.

For everything else, a decision snippet in the PR or issue is enough.

The decision flow¶

Step 1: Write a one-screen pre-read (Driver)¶

Before any discussion, the Driver writes a short document that covers:

Context: Why is this decision needed now? What constraints exist?
Options: 2–3 real alternatives (including status quo if relevant). Pros, cons, risks for each.
Recommendation: What the Driver thinks we should do, and why.
What we need: What decision is being asked for, from whom, by when.

One screen. Not a slide deck. Not a 10-page document. If you can't explain it in one screen, you don't understand it well enough yet.

Step 2: Consult contributors (async, 24–48 hours)¶

Share the pre-read with Contributors. They comment asynchronously. This is for input, not consensus-seeking.

Note disagreements explicitly. If someone has a blocking concern, capture it. These will be addressed in the decision meeting or escalated.

Step 3: Decide (Decider)¶

The Decider reviews the pre-read and comments, then makes the call. For low-stakes decisions, this can happen async. For high-stakes or contentious decisions, a short synchronous meeting (30–45 minutes) is appropriate.

The decision is recorded immediately—either as an ADR or a decision snippet, depending on the classification.

Step 4: Inform and implement¶

Notify the Informed group. Create implementation tickets linked to the decision record. Execute.

Step 5: Review¶

On the scheduled review date (or if signals suggest the decision was wrong), revisit. Adjust or reaffirm.

The pre-read: making it useful¶

A good pre-read answers the reader's questions before they ask them. It respects their time by being concise and complete.

One-screen pre-read template¶

# Decision: [Short name]

**Driver:** [Name] | **Decider:** [Name] | **Contributors:** [Names]
**Decision needed by:** [Date]

## Context and constraints

Why is this decision needed now? What's driving the timeline? What constraints exist (technical, resource, regulatory, etc.)?

## Options

### Option A: [Name]

- Description
- Pros
- Cons
- Risks
- Cost of delay

### Option B: [Name]

- Description
- Pros
- Cons
- Risks

### Option C: [Status quo / Do nothing]

- What happens if we don't decide?

## Recommendation

What I think we should do, and why. What trade-offs am I accepting?

## Risks and safeguards

Is this reversible? What's the rollback plan? How will we know if we were wrong?

## Bottom Line & Ask

What specific decision is needed, from whom, by when?

## Principle upheld

Which principle(s) does this decision support?

Architecture Decision Records (ADRs)¶

ADRs are lightweight documents that capture the context, decision, and consequences of significant architectural or process choices. The format matters less than the habit of writing them.

Why ADRs work¶

They capture reasoning, not just conclusions. Six months from now, knowing that "we chose Postgres" is not useful. Knowing why—and what we considered instead—is.

They onboard new team members faster. Instead of explaining the same decision history repeatedly, you point to the ADR.

They prevent relitigating settled debates. When someone wants to revisit a decision, the first question is "have you read the ADR?" If the context hasn't changed, the decision probably shouldn't either.

They create accountability. A decision with an owner and a review date is a decision that can be evaluated and adjusted.

ADR-lite template (≤1 page)¶

# ADR-[seq]-[slug]: [Title]

**Status:** Proposed | Accepted | Rejected | Superseded by [ADR-xxx]
**Date:** [YYYY-MM-DD]
**Decider:** [Name]

## Context

What problem are we solving? What constraints exist? Why now?

## Decision

What did we decide?

## Alternatives considered

What else did we consider? Why didn't we choose those options?

## Consequences

What are the positive outcomes we expect?
What are the negative outcomes or trade-offs we're accepting?
Who is affected?

## Safeguards

Is this reversible? What's the rollback plan?
How will we monitor for problems?

## Review date

When will we revisit this decision? (Date or condition.)

## Links

- Related PRs/issues
- Design docs
- Metrics dashboards

Naming and storing ADRs¶

Number them sequentially: ADR-0001, ADR-0002, etc. Include a short slug for readability: ADR-0012-grpc-for-internal-apis.

Where to store them: Close to the code they affect. For service-specific decisions, put them in the service repo. For cross-cutting decisions, a central decisions/ folder or wiki.

Maintain an index—a simple list of all ADRs with status, date, and one-line summary. This makes discovery easy.

Decision snippets: for small decisions¶

Not every decision needs an ADR. For reversible, local decisions, a brief record in the PR or issue is enough.

Decision snippet template¶

**Decision:** [One sentence]

**Context:** [Why we needed to decide this]

**Reasoning:** [Why this choice, what trade-offs]

**Reversible within:** [Time or condition]

**Owner:** [Name] | **Date:** [YYYY-MM-DD]

Example¶

**Decision:** Use Redis for session caching instead of in-memory cache.

**Context:** User complaints about being logged out after deploys.

**Reasoning:** Redis persists sessions across deploys. In-memory is simpler but causes session loss on restart. Redis adds a dependency but solves the immediate problem.

**Reversible within:** 2 weeks (can revert to in-memory with a config change).

**Owner:** Sarah | **Date:** 2026-01-15

Common failure modes¶

Failure mode	What it looks like	Mitigation
Decision by DM	Important calls made in private Slack messages with no record	All decisions that affect more than one person get written down
Consensus trap	Waiting for everyone to agree; no explicit Decider	Name the Decider upfront. Disagree-and-commit.
Endless exploration	"Let's look at one more option." No timebox.	Timebox discovery. 2 days for a spike. 48 hours for a pre-read.
Cargo-cult ADRs	Long documents that don't actually make a decision	ADRs must have a clear "Decision" section. If you can't state the decision in one sentence, keep working.
No review date	Decisions become permanent by accident	Every ADR has a review date. Put it on the calendar.
Hidden stakeholders	"Why wasn't I consulted?" after the decision	Explicitly identify Informed parties. Over-communicate, especially cross-team.
Premature standardization	Org-wide mandates before learning from 2–3 teams	Default to team autonomy. Standardize only what's proven.

Escalation¶

When a decision can't be made at the team level—because of cross-team impact, disagreement that can't be resolved, or policy implications—escalate with the pre-read, not vibes.

Escalation path¶

Team TL/EM
Staff Engineer / Architect (for technical decisions)
Engineering Director / CTO (for org-wide standards or significant resource decisions)

When escalating, send the one-screen pre-read with a clear statement of what's blocked and what decision you need from the escalation target.

Rituals¶

Weekly Decision Review (30 minutes)¶

The triad (EM, TL, PM) scans:

Open decisions: What's pending? What's blocked?
Upcoming one-way doors: What irreversible decisions are coming?
Decision debt: What decisions were made without documentation that should be captured?

Architecture Forum (biweekly, 60 minutes)¶

For cross-team ADRs only. Pre-reads required 48 hours in advance. Decisions and outcomes published the same day.

Retro check¶

At each retrospective, ask: "Which decisions went undocumented? What will we capture now?"

Metrics and signals¶

Leading indicators (process health)¶

ADR coverage: What percentage of qualifying decisions have an ADR?
Decision cycle time: From pre-read draft to decision recorded.
Consultation SLA: Are Contributors given 24–48 hours for async review?
Orphan decisions: How many decisions have a Driver but no named Decider?

Lagging indicators (quality)¶

Reversal rate: How often do one-way decisions get reversed? (Very low suggests risk aversion; very high suggests poor decision quality.)
Rework from unclear decisions: Bugs or rework tied to missing or incomplete decision records.
Cross-team integration issues: Problems at team boundaries that could have been prevented by clearer decisions.

Track these at the team level. Never use them to evaluate individuals.

Templates¶

Triage checklist (for Weekly Decision Review)¶

For each pending decision:

- [ ] Is there a **Driver** and **Decider** named?
- [ ] Is the **classification** correct (snippet vs. ADR)?
- [ ] Have **stakeholders** been identified (security, platform, product, design)?
- [ ] Is **reversibility** and **rollback** clear?
- [ ] Is there a **review date** set?
- [ ] Are **implementation tickets** linked?

Decision announcement template¶

## Decision: [Title]

**What we decided:** [One sentence]

**Why:** [Brief reasoning, link to ADR if applicable]

**What changes:** [Impact on teams, systems, processes]

**Effective date:** [When this takes effect]

**Owner:** [Who to contact with questions]

**Links:** [ADR, implementation tickets, relevant docs]

Disagree and commit¶

This phrase gets misused, so let's be clear about what it means.

Before the decision: Disagreement is welcomed. Raise concerns. Propose alternatives. The Driver and Decider should actively seek dissent—that's how you find problems before they become costly.

After the decision: Execute as one team. The time for debate is over. If you disagreed and lost, you still implement the decision with full effort. You don't sabotage, slow-walk, or relitigate in side channels.

The escape valve: If new information emerges that fundamentally changes the context, raise it. Disagree-and-commit is not "pretend to agree forever." It's "execute this decision until we have real reason to revisit."

When disagree-and-commit breaks down

If someone consistently cannot commit after disagreeing, that's a different problem—usually a trust issue or a values misalignment. Address it directly, not through the decision-making process.