DEV Community: Decision Desk

Install a lightweight ADR process in 30 minutes

Decision Desk — Tue, 06 Oct 2026 14:06:57 +0000

By Decision Desk

Part 2 of a short series. Part 1: Ceremony proportional to irreversibility: Type 1 vs Type 2 engineering decisions

Architecture Decision Records have been around since Michael Nygard's 2011 post "Documenting Architecture Decisions." The idea is simple: when you make a significant technical decision, write a short document that captures the context, the decision, and its consequences, and keep it next to the code.

Most teams agree ADRs are a good idea. Many have a docs/adr/ folder with three records from two years ago. The format is almost never the reason the practice dies. It dies because nobody agreed when to write one, how much to write, or what "accepted" means.

This post is a 30-minute install that answers those three questions. You need a repo (or a wiki), one meeting, and a decision your team is making this week.

Before the meeting (5 minutes, one person)

Pick a home. If your team reviews code in GitHub or GitLab, use docs/adr/ in the main repo. Decisions get reviewed in PRs like everything else, and they're versioned with the code they describe. If most of your design work happens in Notion or Confluence, use one database or parent page there. Pick one location. Two locations means zero.

Pick a naming scheme. NNNN-short-title.md, as in 0001-use-postgres-for-billing-events.md. Numbers only go up and are never reused.

Create a stub. Keep it short. A Type 2 record should fit on one screen:

# ADR-NNNN: [Decision, stated as the outcome]

| Field          | Value                                  |
|----------------|----------------------------------------|
| Status         | Proposed / Accepted / Superseded by ADR-____ |
| Date           | YYYY-MM-DD                             |
| Deciders       | @names                                 |
| Classification | Type 1 / Type 2                        |
| Reviewers      | @names                                 |

## Context
What forces a decision now? 3–6 sentences.

## Decision
We will …

## Alternatives considered
| Option      | Why not (one line) |
|-------------|--------------------|
| Status quo  |                    |
| Alternative |                    |

## Consequences
Good: …  Costs we accept: …  Follow-ups (owner, date): …

## Revisit when
A metric, a dependency change, or a date.

Save it as docs/adr/template.md. If you want a well-known format with more structure, MADR (Markdown Architecture Decision Records) is free and widely used. The exact headings matter much less than what follows.

The meeting (30 minutes, whole team)

Minutes 0–5: agree on the goal

Say it plainly: "Decisions that someone will ask 'why?' about get written down before they turn into folklore. Small, reversible ones get a short record. Big, hard-to-reverse ones get a full one. Trivial ones get nothing."

That last sentence is the one that gets buy-in. People resist ADRs because they picture writing four pages for a library bump.

Minutes 5–12: agree on how to classify

This is the step most ADR rollouts skip, and it's the one that keeps the practice alive. Use a simple rule: ceremony proportional to irreversibility.

No record needed: nobody will ask "why?" in six months. The PR description covers it.
Type 2 (easy to reverse): can be fully undone within a sprint, with no data migration, contract change, or other team affected. Use the stub, get one reviewer, done the same day.
Type 1 (hard to reverse): touches data you can't regenerate, sensitive data, or money; needs a migration or coordinated release to undo; creates a contract others build on; or forces other teams to change if you reverse it. Use the stub plus extra sections (non-goals, alternatives in depth, rollback honesty, operability/security), and get reviewers from every affected team.

Two rules for the edge cases: when unsure, go heavier (you can downgrade after five minutes of discussion). And classify the slice, not the project. A big initiative usually contains one or two Type 1 choices and many Type 2 ones.

Minutes 12–20: classify one live decision

Pick something real that's in flight. Not a hypothetical, and not something from last year. Run through the questions out loud. It should take two or three minutes. If people disagree about the type, that disagreement is useful: it usually means someone knows about a dependency or a data implication that others don't.

Decide: Type 1, Type 2, or no record.

Minutes 20–25: assign it

Author: the person closest to the decision, not the most senior person in the room.
Reviewer(s): one for Type 2. For Type 1, one per affected team, plus security or data if relevant.
Due date: Type 2 this week. Type 1 gets a review window of about 3–5 working days, or 48 hours if the cost of delay is high.

Create an index, either a docs/adr/README.md with a table or a view in your wiki database, and add the first row now: ID, title, status (Proposed), type, author.

Minutes 25–30: agree on three rules

"Accepted" requires the reviewer's OK, and for Type 1, cleared blockers. A Type 1 record isn't accepted until the rollback story is honest (separating "flip the flag" from "migrate the data back"), owners are named for implementation and for revisiting, and data or security impact is addressed.
Never edit an accepted decision's substance. If you change your mind, write a new ADR that supersedes the old one and link them both ways. Fixing typos is fine. Rewriting history isn't.
Link records from where the work happens. Put the ADR link in the PR description, the epic, or the RFC. A record nobody can find from the code is only slightly better than no record.

That's the meeting. The process is installed once the next decision goes through it, not once the template is perfect.

The first four weeks

Week 1: the first record gets written and reviewed. Expect it to be a bit long. That's fine.

Week 2: watch for the "do we need an ADR for this?" question. Answer it with the classification questions, out loud, in the channel. This is how the team learns the boundaries.

Week 3: look at the index. If everything is Type 1, your classification is too cautious, or people are only writing records for big decisions and skipping the Type 2 ones. If everything is Type 2 and records are two lines long, check whether anything irreversible slipped through.

Week 4: scan for records stuck in "Proposed" for more than two weeks. Accept them, reject them, or withdraw them. A decision log full of stale proposals signals that decisions don't really get made here.

Optional upgrades, later

Don't add these on day one. Add them when you feel the gap:

CODEOWNERS on docs/adr/ so the right people are auto-requested on ADR PRs.
A tradeoff worksheet for Type 1 decisions with several real options: weighted criteria, plus a line for where judgment overrode the scores.
A review scorecard for contentious decisions, filled in independently before discussion, to show where reviewers actually disagree.
CLI tooling like adr-tools to generate numbered files, if your team likes that.
A quarterly skim of accepted Type 1 records against their revisit triggers.

Common ways this goes wrong

The architect writes all the records. Then it's a documentation job, not a team practice. Authors should be the people closest to the decision.
Records get written after the fact to justify a choice. Some of that is fine, since backfilling a few important past decisions is useful. But if every record is retroactive, the review step is theater.
The template grows. Every incident adds a section. Resist it. Keep the Type 2 stub on one screen and put additions in the Type 1 extras.
No "no record needed" category. Without it, people either document everything and burn out, or document nothing and feel guilty.

Thirty minutes, one folder, one stub, three rules. The value shows up six months from now, when someone asks "why did we do it this way?" and the answer is a link.

If you'd like the classification step as a printable one-pager, the free Decision Classifier has the 7 yes/no questions, the ceremony for each outcome, a minimal ADR stub, and three worked examples: https://decisiondeskeng.gumroad.com/l/vbowoo

Ceremony proportional to irreversibility: Type 1 vs Type 2 engineering decisions

Decision Desk — Fri, 02 Oct 2026 13:24:28 +0000

By Decision Desk

Every engineering team eventually has the same argument. One group says "we need more design review, we keep shipping things we regret." Another says "we need less process, it takes three weeks to change a config value." Both are usually right, about different decisions.

The fix isn't more process or less. It's matching the process to how hard the decision is to undo. That idea has a well-known framing, and it's worth being precise about how to apply it to engineering work.

One-way doors and two-way doors

Amazon's 2015 shareholder letter described two types of decisions. Type 1 decisions are "one-way doors": consequential and nearly irreversible, so they deserve slow, careful deliberation. Type 2 decisions are "two-way doors": if you walk through and don't like it, you walk back. Those should be made quickly, by small groups or individuals.

The letter's warning was about a specific failure: as organizations grow, they start using the heavyweight Type 1 process for everything, including the Type 2 decisions. The result is slowness, risk aversion, and not enough experimentation.

Engineering teams make the opposite mistake just as often. They treat a one-way door like a two-way door because the change looks small. It's a single PR, it's behind a flag, "we can always roll back." Then they discover the rollback only covers the deploy, not the data, the contract, or the three teams that started depending on it.

So the rule is ceremony proportional to irreversibility: the harder a decision is to reverse, the more review and documentation it gets. The easier it is to reverse, the faster and lighter you go.

Operational rollback isn't architectural reversal

This distinction does most of the work, and it's where teams misclassify.

Operational rollback is what your deploy tooling gives you: revert the commit, flip the flag, drain traffic. It takes minutes.

Architectural reversal is what it costs to make the decision not have happened:

Data written in a new format has to be migrated back, or read by two code paths forever.
A public API field that clients now parse can't be removed without a coordinated release or a version bump.
A vendor contract has a term. A protocol choice has a whole ecosystem of clients.
Another team built a feature assuming your event shape. Now it's their roadmap too.

A feature flag can make operational rollback instant while architectural reversal still takes a quarter. When someone says "it's reversible, it's behind a flag," the follow-up question is: what does the flag not undo?

Signals that you're looking at a one-way door

You don't need a scoring model to spot Type 1 decisions. These questions catch most of them:

Does it touch data you can't regenerate, personal or regulated data, money, or security boundaries? Mistakes here tend to be permanent, even when the code change is small.
Could you fully undo it within a sprint, with no data migration, dual-write, or coordinated client release? If not, it's a one-way door.
Does it create something others will build against for a year or more? Public or cross-team APIs, event schemas, storage formats, protocols, vendor commitments.
Would undoing it require another team to change their code or plans? Reversal cost scales with the number of teams involved.

If none of these are true, you're almost certainly looking at a Type 2 decision, and the best thing you can do is decide quickly.

What "ceremony" means at each level

"More process" is vague. Here's a concrete version that works for small and mid-sized teams:

	No record needed	Type 2	Type 1
Record	PR description	One-page decision record	Full record, 2–4 pages
Alternatives	—	Status quo + one alternative, one line each	Status quo + at least two real alternatives with tradeoffs
Review	Normal code review	One reviewer, async, same day	Named reviewer from each affected team; security or data owner when relevant; 3–5 day window
Done when	PR merges	Reviewer agrees	Blockers cleared: honest rollback story, named owners, data/security addressed
Revisit	—	Optional date	Explicit triggers: a metric, a date, or an event

The "no record needed" column matters. If your process demands a document for renaming a private function, people will route around the process for everything. Letting trivial choices go undocumented is what makes the Type 2 record feel cheap enough to actually write.

Three examples

Flipping a feature flag default from off to on. Usually Type 2. Operational rollback is instant, and if no data format or contract changes, architectural reversal is instant too. Write one page, get one reviewer (ideally from support or product, since customers will notice), and set a date to remove the flag. It becomes Type 1 if the new code path writes data the old path can't read, or changes consent or tracking defaults.

Choosing the primary datastore for a new service. Almost always Type 1. Switching later means a backfill and a dual-write period, and if the data feeds invoices or audits, the first signal (data you can't regenerate, money) applies as well. Full record, reviewers from whoever will operate it, and a real comparison of alternatives.

A breaking change to a public API. Type 1. Once clients migrate, the change is permanent. What's interesting is that you can often split out a reversible first step: add the new fields to the existing version as optional and additive, which is Type 2, while the breaking version goes through full review.

The trick that makes Type 1 faster

People resist Type 1 process because it's slow, and sometimes the cost of delay is real. The answer isn't to skip the record. It's to ask one question before the review starts:

Can we split out a reversible first step?

Shadow-write to the new store while the old one stays authoritative. Ship the new endpoint behind a flag to one internal client. Take a 30-day vendor trial instead of a 3-year contract. Each of these turns part of a one-way door into a two-way door, lets you gather evidence, and shrinks the irreversible part to something smaller and better informed.

When you genuinely can't split it and time matters, shrink the review window, not the record: a 48-hour async review with a decision date written on the page.

When you're not sure

Two rules handle most of the ambiguity:

When unsure, go heavier. Downgrading a Type 1 to Type 2 after a five-minute conversation costs five minutes. Discovering in production that a "quick change" was a one-way door costs a migration.
Classify the slice, not the project. A large project usually contains one or two irreversible choices, like a schema or a contract, surrounded by many reversible ones. Give the irreversible slice full ceremony and let the rest move fast.

Precedent is the subtle one. A reversible choice that every team will copy without thinking, like the default logging library or the default test runner, is still Type 2. But it deserves a record, because "why is this the default?" is exactly the question people will ask.

The payoff

When ceremony tracks irreversibility, a few things change:

Engineers stop asking "do we need an ADR for this?" because there's a two-minute answer.
Review time concentrates on the handful of decisions that can actually hurt you.
The decision log fills up with useful short records instead of a few abandoned long ones.
New engineers can read why the system looks the way it does, for the decisions that matter.

None of this needs tooling. It needs a shared definition of which door you're walking through.

Next: Install a lightweight ADR process in 30 minutes

If you want to try this on a real decision, we put together a free one-page Decision Classifier: 7 yes/no questions that end in Type 1, Type 2, or "no record needed," a minimal ADR stub, and three worked examples (API versioning, database choice, feature flag default). It's here: https://decisiondeskeng.gumroad.com/l/vbowoo