# An ADR without a customer problem is just a solution brief

> Map each architecture decision from a named customer problem to a measurable outcome before you compare Azure options.

- Canonical: https://www.architecture-logic.com/ground-every-adr-in-a-customer-problem
- Published: 2026-10-26
- Updated: 2026-10-26
- Claims verified: 2026-10-26
- Category: Architecture decisions
- Tags: Architecture Decision Records, Azure, Governance, AL Trace

## Revision history

- 2026-10-26 (published): First What's New publication on problem-to-outcome ADRs.

## Sources

- [Architectural Decision Records (ADRs) — Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/architecture-decision-records) (verified 2026-10-26)
- [Azure Well-Architected Framework — Tradeoff](https://learn.microsoft.com/en-us/azure/well-architected/) (verified 2026-10-26)

---

An architecture decision record that never names the customer problem is a solution brief with a date stamp.

That is the failure mode I keep seeing in Azure programs. The ADR opens with "we will use Private Endpoints" or "we selected Service Bus" and the review room debates SKUs. Nobody can say which user journey still fails if the decision is wrong. The record looks mature. The operating loop is empty.

## Start with the failure a customer can feel

A useful ADR answers four questions before it compares products:

1. Who is stuck, and what are they trying to finish?
2. What outcome would prove the stuckness is gone?
3. Which requirements are non-negotiable because of that outcome?
4. Which option do we accept, who owns it, and what evidence would force a revisit?

Until those are written, Azure icons are decoration. Microsoft's own [ADR guidance](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/architecture-decision-records) treats the record as a decision aid, not a product announcement. The decision only earns its place when the problem and the consequence are explicit.

Here is the chain that should exist for every ADR, including the ones that feel "obvious":

```mermaid
# caption: The ADR sits after problem and outcome; evidence can reopen the decision
flowchart LR
  problem[Customer problem] --> outcome[Intended outcome]
  outcome --> requirements[Requirements]
  requirements --> options[Options and tradeoffs]
  options --> adr[Accepted ADR]
  adr --> evidence[Evidence and revisit]
  evidence -->|outcome missed| problem
```

Read that left to right when you propose a change. Read it right to left when production lies. If you cannot walk back from a failing metric to the ADR that claimed the outcome, you do not have decision hygiene. You have documentation.

## A concrete Azure example

Take a checkout journey that times out under afternoon load. The customer problem is not "we need Front Door." The customer problem is "buyers cannot complete payment before the session drops." The intended outcome might be "p95 checkout completion under 400 ms at the edge for the payment step, measured in Application Insights for the production app."

Only then do the Azure options earn a page:

```azure-architecture
# caption: Checkout outcome drives edge, app, and telemetry ownership before SKU debate
zone: Customer | Buyers completing payment
Browser | user | Session and payment step
zone: Edge | Public entry owned by platform
Azure Front Door | front-door | TLS, WAF, and route to the app
zone: Workload | App team owns release and scale
App Service | app-services | Checkout API
Azure Cache for Redis | cache-redis | Session and cart hot path
zone: Evidence | Shared observability
Application Insights | application-insights | p95 and failure rate for payment
flow:
Browser -> Azure Front Door | HTTPS | data
Azure Front Door -> App Service | HTTPS | data
App Service -> Azure Cache for Redis | Cache get/set | data
App Service -> Application Insights | Telemetry | control
controls:
Azure Policy | policy | Deny public app endpoints outside Front Door
operations:
Outcome owner | Checkout product manager
Revisit trigger | p95 over 400 ms for three consecutive peak hours
decision:
Front Door stays at the edge | Revisit if a private-only partner path appears
```

The ADR that follows can accept Front Door plus App Service plus Redis. Or it can reject Redis and accept a different cache boundary. What it cannot do is start with "Redis is strategic" and invent the customer problem afterward. That is how teams inherit platforms nobody can retire.

> **Revisit:** When the outcome metric is missing, disputed, or owned by nobody, stop comparing Azure options. Rewrite the problem and outcome first; the ADR is not ready.

Listeners hear the same rule without the diagram: name the customer failure and the metric before you name Front Door, App Service, or Redis. The icons only illustrate a choice that already has an outcome owner.

## Keep the chain visible with AL Trace

Architecture Logic built [AL Trace](/platform/al-trace) for this discipline: record the problem, the intended outcome, and the requirements before options are compared, then freeze the accepted ADR with linked evidence. Planned results stay distinct from recorded results. When the design changes, a successor decision keeps the earlier reasoning instead of overwriting it.

AL Trace does not make the architecture decision. People still own acceptance. The product's job is narrower and harder: make the problem-to-outcome chain inspectable so a review cannot skip the customer. If your wiki ADR already does that with ruthless consistency, keep the wiki. If your ADRs routinely open on the technology line, you need a structure that refuses to skip the problem.

## What to do Monday

Pick one ADR written in the last quarter that still governs production.

1. Write the customer problem in one sentence a non-architect would recognize.
2. Write the intended outcome as a metric, an owner, and a time window.
3. Highlight every Azure service named in the ADR. Delete any service that does not move that outcome.
4. Add the revisit trigger: the evidence that would force a successor ADR.
5. Link the problem, outcome, ADR, and evidence in one place your team already opens in a design review. If you use AL Trace, record them as linked records; if you do not, put the same four headings at the top of the ADR template and reject drafts that leave them blank.

Do that for three decisions and the pattern becomes obvious. Solution-first ADRs feel unfinished. Problem-first ADRs feel operable.

## The share test

If you forward an ADR to a product owner and they cannot tell whether their customer got faster, safer, or unblocked, the record failed before the first Azure icon appeared.

Where do your ADRs usually start today: the customer problem, or the preferred platform?