The problem with verbal proposals
You've mapped the data flow. You've counted the automations that exist just to keep two systems in sync. You've done the math on what the team is paying — in subscription fees, maintenance hours, and failure surface — for a tool that handles three functions the primary system already covers.
You say it out loud in a check-in. The response is fast: "It's not an option." The conversation moves on. Your analysis evaporates.
This happens because verbal proposals in busy meetings trigger a predictable response: when someone hears "remove something," their default is to protect the status quo. It's not that your idea was wrong. It's that the format gave them no time to think, no evidence to evaluate, and no path to follow.
ADRs originated in software engineering, popularized by Michael Nygard in a 2011 blog post. But the format is useful far beyond code. If you design systems, integrations, or operational workflows — and you need other people to approve changes — this is the document that makes your case without requiring you to win an argument in real time.
The structure
An ADR has seven sections. Each one serves a specific purpose in the decision-making process. The entire document should fit on one or two pages — this isn't a whitepaper. It's a decision tool.
A real example
Here's what a complete ADR looks like in practice. The scenario: a property management client's automation stack includes a field service management tool that was added early in the build. Six months in, most of the operational data lives in a different system, and the FSM tool is barely being used.
Subscription cost vs. value delivered
Data integrity risk from dual-system sync
Client team cognitive load (two interfaces for one workflow)
Migration effort and timeline
Future scalability of the chosen path
Then comes the comparison. The options table should be honest about tradeoffs — including the costs of staying put.
| Option | Pros | Cons |
|---|---|---|
| A. Keep as-is | No migration effort. No change management. Familiar to the team. | Ongoing sync maintenance. Limited FSM features at current tier. Two systems for one workflow. |
| B. Upgrade FSM tier | Unlocks role filtering. Uses the platform as designed. | Higher subscription cost. Sync automations still required. Doesn't address data living in the wrong system. |
| C. Consolidate into primary system | Eliminates 6 sync automations. Single source of truth. Reduces failure surface. Lower total cost. | Requires building work order assignment and notification features. One-time migration effort. Change management for field team. |
Option C — consolidate into the primary system. The FSM platform's current usage (three functions) does not justify the maintenance cost of six sync automations and a separate subscription. The primary system already contains all entity data and has the extensibility to handle work order assignment and completion notifications natively. Estimated migration effort: 2–3 weeks. Net automation reduction: 6 removed, 2 added.
Pending team review. This ADR is open for discussion until [date].
Why this format works
The ADR structure does several things that a verbal suggestion in a meeting cannot.
It separates the idea from the moment. A busy check-in is optimized for status updates, not architectural decisions. When you propose a system change verbally, you're asking people to evaluate, react, and decide simultaneously. The ADR gives them space to read, think, and respond on their own terms.
It separates the idea from the person. When you say "we should drop Tool X" out loud, the person who chose Tool X hears "your decision was wrong." The ADR reframes it: the requirements changed, the usage evolved, the data tells a different story now. That's not failure — that's growth.
It makes "keep as-is" a visible choice. Most teams default to inaction without realizing it's a decision. By listing "keep as-is" as Option A with its own costs spelled out, you make the status quo compete on equal terms with the alternatives. Suddenly, doing nothing has a price tag.
It survives the meeting. A verbal suggestion disappears in thirty seconds. An ADR stays on the table. Even if the answer is "not now," the document exists. When the pain gets worse — when the seventh sync automation breaks at 2 AM — someone will remember there's a document that already maps the way out.
When to write one
Not every decision needs an ADR. Changing a field name in Airtable doesn't warrant a document. But there are clear signals that one is needed.
That last one is the most practical trigger. If you've said it out loud and it was dismissed — not because it was wrong, but because the format didn't give it a chance — write the ADR. You're not being stubborn. You're being an architect.
The template
Here's the bare structure. Copy it, fill it in, keep it to one or two pages. The constraint is the point — if you can't make the case concisely, the case isn't ready.
One last thing
The hardest part of growing into an architect role isn't seeing what should change. It's learning that how you present the change matters as much as the change itself.
An ADR won't guarantee your recommendation gets accepted. But it guarantees it gets considered. And over time, the pattern compounds: when you consistently show up with structured, evidence-based proposals, people start trusting your judgment before they even read the document.
The goal isn't to win arguments. It's to make the best option visible — and let the decision happen.