Topic: ADR decision authority matrix
ADR Decision Authority Matrix — Who Writes, Reviews, and Approves
The most common reason ADR adoption stalls after the first ten decisions isn't the template, the tooling, or the file format — it's that nobody knows who is allowed to mark an ADR Accepted. When the approval path is ambiguous, ADRs sit in "Under Review" indefinitely, authors stop writing them, and the archive quietly rots. A decision authority matrix makes the approval chain explicit: for each class of architecture decision, who writes it, who reviews it, and who has the organizational authority to close it.
TL;DR
Map each class of architecture decision to a Responsible (author), an Accountable (approver), a Consulted set (technical reviewers), and an Informed set (stakeholders). Implementation decisions scoped to a single service can be self-approved with tech lead visibility. Decisions that cross service boundaries, change shared contracts, or affect shared infrastructure require a principal or staff engineer as Accountable. Security-relevant decisions require a security review before Accountable signs off. Keep approval chains to one approver — every additional required approver reduces the rate at which engineers write ADRs. Record the Accountable identity in the ADR's deciders: frontmatter field so the approval is visible in the file, not just in a PR comment that disappears.
The authorship–authority split
In most ADR templates the engineer who identifies the decision, researches the alternatives, and writes the document is not the same person who should hold organizational accountability for the outcome. Conflating the two roles is the single biggest governance failure in ADR adoption:
- Self-approval on every ADR means the file is a log of the engineer's choices, not a record of the organization's committed positions. New engineers who join later have no way to know whether the "Accepted" status means "the team agreed" or "the author decided unilaterally and filed the paperwork."
- No clear Accountable role means decisions that should involve a second perspective (API contract changes, infrastructure choices, cross-team dependencies) get approved without that perspective — or, more often, stall indefinitely because no one feels empowered to mark them Accepted.
The authority matrix solves both problems by making explicit: for this class of decision, this role is Accountable and must mark the ADR Accepted before it enters the canonical archive.
Decision classes and their authority chains
Five decision classes cover the majority of architecture decisions in engineering teams at 5–50 people. The class is determined by the decision's impact radius — how many teams, services, or engineers are affected by the Consequences section.
| Decision class | Examples | Responsible (author) | Accountable (approver) | Consulted | Informed |
|---|---|---|---|---|---|
| Implementation — internal to one service, no external observable effects | Caching strategy, internal refactor, library upgrade inside a single service | Service owner engineer | Author self-approves (tech lead visibility via PR) | Tech lead (optional) | Team |
| Service architecture — shapes the service's external interface or internal structure durably | Database choice, event sourcing vs CRUD, adding a queue, service decomposition | Engineer or tech lead | Tech lead or EM | Adjacent service owners | Product manager, team |
| API contract — changes an interface used by other teams | Breaking API version, new shared event schema, deprecation of a public endpoint | Engineer or tech lead | Principal or staff engineer | All consuming teams, platform team | CTO, product managers |
| Data / schema — changes shared data structures or storage ownership | Schema migration with backward-incompatible changes, new shared database, data ownership boundary change | Engineer or tech lead | Tech lead or EM + data team lead | DBA or data engineer (if present), platform team | Analytics, product, CTO |
| Infrastructure / ops — changes shared infrastructure or operational responsibilities | Cloud provider, orchestration platform, observability stack, disaster recovery approach | SRE or infrastructure engineer | SRE lead or VP Engineering | Security team, cost center owner | CTO, finance (for cost-significant changes) |
| Security-relevant — any decision that changes the attack surface, auth model, or data handling | Auth mechanism change, new third-party data processor, encryption-at-rest decision | Engineer or tech lead | Security lead or CISO; Accountable cannot sign off until Consulted security review is complete | Security team (required, not optional) | Legal, compliance, CTO |
At teams smaller than ten engineers the Accountable role for service architecture and API contract decisions typically collapses to the CTO or tech lead who is also the author's manager. That is fine — the matrix still functions as a clarity tool: the author knows who to tag in the PR, and the approver knows they are closing a committed position, not just leaving a review comment.
Encoding the authority matrix in your ADR frontmatter
The deciders: field in Nygard-style YAML frontmatter is where authority is recorded in the file itself. The common mistake is using deciders: as a list of everyone who commented on the PR rather than as the list of people who held the Accountable and Consulted roles:
---
title: "Replace Redis with Postgres LISTEN/NOTIFY for intra-service events"
status: Accepted
date: 2026-05-21
deciders: ["@alice (tech-lead, Accountable)", "@bob (SRE, Consulted)"]
supersedes: ""
---Annotating each decider's role in the list (Accountable vs Consulted) makes the authority chain readable to someone who inherits the ADR two years later and does not know the team structure from the time the decision was made.
The status: field evolution mirrors the authority flow:
- Proposed — author has drafted the ADR and assigned it to Accountable for initial review.
- Under Review — Consulted reviewers are actively engaged. The ADR must not move to Accepted until all Consulted parties have had the opportunity to respond (a time-boxed review window — typically 3–5 business days — prevents indefinite stalling).
- Accepted — Accountable has marked the ADR closed. The file is committed to the canonical archive. No further prose editing without reopening via a supersession.
Time-boxing the review window
The most common cause of ADRs that never leave "Under Review" is an unbounded review window: Consulted parties have no deadline, so they defer review indefinitely. Time-boxing fixes this:
- Set a review deadline in the ADR PR description (e.g., "Consulted reviewers have until 2026-05-28 to raise blocking concerns. Silence is consent.").
- After the deadline, the Accountable marks the ADR Accepted if no blocking concerns were raised — or escalates a blocking concern to a decision by the approver. Consulted reviewers do not have veto power; only the Accountable holds decision authority.
- Record the review window in the ADR's
reviewed-by:field if your template includes one, so the audit trail shows who was given the opportunity to review, not just who actually commented.
Anti-patterns to avoid
Anti-pattern 1: Self-approval on everything
When every engineer marks their own ADRs Accepted without a second review, the archive is a personal log, not an organizational record. The symptom is ADRs that conflict with each other because no one with cross-team visibility reviewed either one. The fix is applying the impact-radius rule: if the Consequences section describes effects beyond the author's direct ownership boundary, a second Accountable is required.
Anti-pattern 2: Over-centralization
Requiring the principal engineer or CTO to approve every ADR — regardless of impact radius — creates a review bottleneck. When the Accountable role is always the same high-load person, engineers learn to write fewer ADRs because the approval queue is slow. The fix is delegating Accountable to the lowest-authority person whose ownership boundary encompasses the full impact radius. A tech lead who owns three services can be Accountable for a decision that affects all three.
Anti-pattern 3: Treating Consulted as blocking approvers
Some teams add every stakeholder as a required reviewer in their PR tool — meaning any of them can block the merge indefinitely. Consulted reviewers have advisory authority, not veto authority. Only the Accountable blocks. If a Consulted reviewer raises a concern that the Accountable disagrees with, the Accountable makes the call, records the disagreement in the ADR's Consequences section ("Alice raised a concern about X; we accepted this risk because Y"), and marks the ADR Accepted. The concern is preserved in the record without blocking the decision.
Anti-pattern 4: Approval authority not recorded in the file
When the Accountable's identity exists only in a PR comment or a Slack thread, it is invisible to anyone reading the ADR file three years later. Record the Accountable identity in the deciders: frontmatter field so the approval is durable. PR comments are archived but not easily navigable; the frontmatter field is the first thing a reader sees when they open the file.
Authority matrix at different team sizes
The matrix simplifies as team size decreases and compresses as it grows:
- 1–5 engineers: All decision classes route to the same Accountable (the founder-CTO or tech lead). The matrix still matters because it establishes the habit of explicit approval — the founder-CTO who marks every ADR Accepted is building the muscle memory that survives the first engineering manager hire.
- 5–20 engineers: Implementation decisions self-approve; everything else routes to the tech lead or EM. A staff or principal engineer role may not exist yet — the CTO holds the API contract and infrastructure Accountable roles until someone is promoted or hired into them.
- 20–50 engineers: The full five-class matrix becomes necessary. At this size, without an explicit matrix, API contract decisions get approved by whoever is most available rather than whoever has the most context — producing conflicting ADRs in different service directories. A principal engineer or architecture review board (ARB) holds the API contract and infrastructure Accountable roles.
- 50+ engineers: The matrix typically becomes a formal Architecture Review Board policy. The ARB holds Accountable for the top two decision classes (API contract, infrastructure); service teams hold Accountable for implementation and service architecture; a security committee holds Accountable for security-relevant decisions. ADR templates often add an
adr-class:frontmatter field at this scale so CI can route each ADR to the right review queue automatically.
Connecting the authority matrix to AI-assisted decision-making
A growing share of architecture deliberation happens in ChatGPT and Claude sessions — the engineer works through trade-offs with an AI assistant before writing the ADR. This introduces a gap: the AI session where the decision reasoning was developed is not visible to the Accountable reviewer, who sees only the finished ADR text.
Two practices close this gap:
- Link the AI session in the ADR. Add a
deliberation-record:field or a "Deliberation Record" section to the ADR that references the WhyChose-extracted decision record or a share link to the relevant conversation. The Accountable reviewer can read the AI-assisted reasoning that produced the ADR, not just the cleaned-up conclusion. - Extract informally-approved decisions retroactively. When a senior engineer exports their ChatGPT or Claude history and runs the WhyChose extractor, the output frequently surfaces decisions that were made informally in AI chat sessions and never written as ADRs — meaning the Accountable role was never invoked. These extracted decision records become the input to the ADR writing process, bringing informal decisions into the authority matrix retroactively.
Related questions
Who should mark an ADR as Accepted?
The engineer or EM with organizational authority over the decision's impact radius — not necessarily the author. For single-service implementation decisions, the author may self-approve with tech lead visibility. For decisions that cross service boundaries, change API contracts, or affect shared infrastructure, the Accountable role belongs to the principal engineer, staff engineer, or EM who owns the affected boundary. The person who marks the ADR Accepted is accountable for the consequences described in it — that accountability should sit with someone who has the organizational standing to own the outcome.
Should engineers be allowed to self-approve their own ADRs?
Yes, for well-scoped implementation decisions that fall entirely within the author's ownership boundary. The rule of thumb: self-approval is appropriate when the entire Consequences section describes effects that are the author's own responsibility to manage. If any Consequence describes an obligation for a different team or a change to a shared boundary, a second approver from that boundary is required. A well-designed authority matrix makes this boundary explicit so engineers don't have to guess on each ADR.
How many approvers should an ADR require?
One is usually correct. Two is right for cross-team API contract decisions and security-relevant changes. Three or more is almost always wrong — it typically signals that the ADR's scope is too broad (should be split) or that the approval process has been over-engineered. Every additional required approver reduces the rate at which engineers write ADRs, because slow approval teaches engineers to avoid the process. The guiding question: who has genuine accountability for the Consequences? That usually points to exactly one person beyond the author.
What is the difference between a Consulted reviewer and an Accountable approver?
A Consulted reviewer provides technical input and raises concerns before the ADR is finalized — their feedback shapes the decision, but they do not hold decision authority and cannot block the ADR indefinitely. An Accountable approver marks the ADR Accepted and is organizationally responsible for the consequences. If a Consulted reviewer raises a concern the Accountable disagrees with, the Accountable makes the call, records the disagreement in the ADR, and marks it Accepted. Treating all reviewers as blocking approvers is the most common way to produce an "Under Review" graveyard.
Further reading
- ADR review checklist — what to look for before marking Accepted — the checklist for what the Accountable reviewer should verify before marking an ADR Accepted. Covers the structural, prose, and consequence completeness checks that catch common ADR deficiencies before they enter the canonical archive. Complements the authority matrix by answering "who approves" (this page) and "what do they check" (the review checklist).
- When to write an ADR — the threshold question — before the authority matrix applies, the engineer must decide whether a decision warrants an ADR at all. The threshold page explains the impact-radius heuristics that trigger the ADR process; this page explains what the approval chain looks like once the process is triggered. The two pages form a complete governance pair.
- How to introduce ADRs to your team — a pragmatic adoption guide — authority clarity is one of the biggest blockers to team-wide ADR adoption. The adoption guide covers the organizational change management that accompanies the technical setup; the authority matrix is the governance artifact that makes "who approves" answerable at adoption time rather than six months in when the first contested ADR surfaces.
- ADR template for product squads — squad-level ADR governance for product teams that follow a squad-and-tribe model. The authority matrix collapses to a two-tier structure in squads (squad tech lead for service architecture decisions, chapter lead or principal engineer for cross-squad decisions) — the squad template operationalizes the authority boundaries described in this page for that specific model.
- Architecture decision record best practices — the synthesis page for all ADR governance disciplines. The authority matrix is one of the key practices for keeping an ADR archive authoritative and alive; the best-practices page situates it alongside review cadence, supersession discipline, and link hygiene as a complete governance system.
- ADR GitHub Action — CI enforcement for structure and status — the GitHub Action that enforces the controlled vocabulary in the
status:anddeciders:frontmatter fields on every pull request. CI enforcement makes the authority matrix machine-checkable: an ADR without a populateddeciders:field fails the pipeline, so the Accountable identity cannot be omitted accidentally. - ADR change management template — linking ADRs to ITIL and CAB approvals — for teams in regulated environments, the engineering authority matrix described on this page sits beneath a second CAB approval layer. The change management template covers the ADR-CM variant (four ITIL-specific frontmatter fields), the division of ownership between the ADR and the Change Record, and the emergency change edge case — the governance layer that applies after the authority matrix decides who approves the ADR.
- ADR governance patterns — async teams and the RFC announcement loop — the process complement to the authority matrix: the matrix says who has the authority to Approve; the governance patterns page describes the ceremony that makes approval actually happen in distributed and remote-first teams. Covers announce-then-silence (the merge-if-silent default that prevents review deadlock), decision classification by scope, and the four anti-patterns that stall ADR adoption despite a clear authority model.
- Engineering principles template — ADR vs principle, the promotion path, and the standing-rule repository — the complement to the authority matrix at the policy level: the matrix answers "who approves this specific ADR"; principles answer "what's the default we apply so not every similar decision requires a new ADR." When three or more ADRs routed through the authority matrix reach the same conclusion, those decisions are candidates for promotion to a standing principle — reducing the ADR volume the matrix needs to process for the default case.