Maven Live · LL2 · 19 May 2026 · 7pm London

The ADR that gets you
promoted.

Free 30-minute live workshop. Write your first Architecture Decision Record together, and use it at work tomorrow.

Ehsan Gazar
Principal Engineer · gazar.dev
Why this matters

Decisions vanish.
Consequences don't.

A team picked NoSQL with no written rationale. The lead left six months later. Eighteen months after that, a rewrite cost £200K. The choice may have been right. Nobody could tell.

1
Decision made
no written rationale
month 0
2
Lead leaves
context walks out the door
+ 6 months
3
Migration forced
3 months · ~£200K
+ 24 months
The format

An ADR is three parts.
That's it.

One page. Ten minutes to write. Lives in the repo forever. Each part has a job; if a part is missing, the document fails the test.

C
Context
Situation, constraints, what we're solving for. Name 3-4 things.
the why
D
Decision
What we decided. Stated plainly. One sentence.
the what
×
Consequences
+ enables, − costs, and the revisit condition.
the trade
Worked example

ADR-001 · Database for the Payments service.

Context
10K TPS peak writes. Predictable access (by id, by customer).
Isolated service. Team strong on PostgreSQL. Ship in 6 weeks.
Decision
We will use PostgreSQL, not DynamoDB.
Consequences
+ Team moves fast, no learning curve
+ Full ACID, regulatory requirement for payments
+ Ad-hoc reporting queries trivial later
− Horizontal scaling work past 100K TPS
− Accepted risk at current 10K TPS peak
− Revisit at 50K TPS sustained

↑ the revisit condition is what makes this a staff-level document

Your turn · 4 minutes

Notification service:
own queue, or SQS / Pub/Sub?

Write 2-3 sentences for each part. Include at least one +, one −, and a revisit condition. Drop your answer in chat.

C
Context
Name 3-4 constraints
(scale, team, deadline, failure mode)
D
Decision
State it plainly.
No hedging.
×
Consequences
+ enables, − costs,
revisit when…
timer
4:00
The career payoff

Three reasons ADRs end up
in promotion packets.

1
Visible thinking
Committees aren't in your design reviews. They read what you've written.
artefact
2
Faster onboarding
20 ADRs and a new hire understands your codebase's values in an afternoon.
leverage
3
Seniority signal
Juniors decide. Seniors document. Principals build the culture of it.
level
this is what moves senior → staff ↑
Cohort 1 · starts June 2, 2026

Senior to Staff Engineer.

Six weeks. Twelve live sessions. Three ADRs with real stakeholder pressure and direct feedback on your writing. Small cohort so feedback is actually personal.

Enrol
link is in the chat ↑
Take-home template
Use the ADR format at work tomorrow.
also in the chat