Your First Architecture Review — How to Run It

The first architecture review I ran ended in eleven minutes with everyone agreeing, and I was pleased about that. Four months later we were rewriting the upload path in production, because the virus scanner came back with its verdict long after the client had received its 200 OK and moved on.

Nobody in that room had read the design doc. What I recorded as agreement was nine people declining to say out loud that they'd skimmed the title and joined the call. The design shipped anyway — now with a meeting attached to it as evidence that someone had checked.

Silence didn't mean the design was sound. It meant the doc was unread.

The Review Decides Almost Nothing — And That's the Point

The first time you're handed one of these, the meeting feels like the decision — you at the front of the room, walking a senior audience through your diagram, and either they bless it or they don't.

That's not what's happening. By the time people sit down, one of two things is already true. Either they've read the document, and the meeting is where their objections get to argue with each other — or they haven't, and the decision quietly goes to whoever talks most confidently for the longest.

Which means the meeting isn't where the design gets evaluated. It's where you find out whether the evaluation happened.

The value isn't that problems get discovered in the room. It's that they get discovered while the design is still cheap to change. A cross-cutting concern that surfaces during review costs you a paragraph. The same concern surfacing after launch costs you a migration.

You're also not collecting votes. The advice process puts the rule about as bluntly as it can be put: whoever makes the decision has to seek out everyone meaningfully affected and everyone with real expertise — and is under no obligation to agree with a word of it. Not consensus. Input, on the record.

So the artifact you're producing isn't an approval. It's a ledger of objections.

Prep Is the Review — The Question That Produces Objections

Send three things, two days out: the design document, one sentence naming the decision you're asking for, and a short list of what is already fixed. That last one saves you twenty minutes of someone relitigating why the project exists.

Then attach the ask. This is the part everybody gets wrong.

"Any comments?" produces a thumbs-up react. It's a question you can satisfy without opening the document. Ask this instead:

Name the failure you'd be paged for.

That question does something the polite version can't — it asks people to protect themselves. A non-answer becomes visible, and it routes around the instinct to comment on naming rather than on risk.

Here's what it produced the second time around, on the same upload design. The proposal was to move file uploads off the app server to pre-signed S3 URLs, with a virus scan running in the background afterward.

Two replies came back before anyone sat down. The engineer who owned our storage asked who was going to own the bucket lifecycle policy, because the current one deletes objects at ninety days and some of these uploads are legal records. Someone from payments asked what the client is supposed to do when the scan fails on a file we already returned 200 OK for.

Neither of those is a comment on the design. Both of them are the design being wrong.

The mechanism isn't mine. Derek Parham's team ran a version of it at Google and later on a campaign engineering team: a separate blank document alongside the design doc, questions listed with the name of whoever asked, those questions becoming the agenda. Take the mechanism. What I'd add is the wording — and one rule about what to do when nobody answers.

It isn't free, though. Asking for failures instead of comments reads as adversarial the first couple of times — say out loud that it's the format talking, not the room's opinion of the work. And it only works on an unfinished document. A polished doc invites comments on the polish; a doc with an open question sitting in the middle of it invites someone to answer the open question.

The Cancel Rule — What to Do When Nobody Read It

If the morning of the review arrives and nobody has written anything, cancel it.

Not reschedule-with-a-recap. Cancel. The instinct is to be accommodating — spend the first fifteen minutes walking everyone through the doc so the time isn't wasted — and that instinct destroys the format permanently. Do it once and you've taught the room that the pre-read is decorative.

The honest counter-argument is Amazon's, and it's a good one. They solve the same problem by not relying on the pre-read at all: the memo gets read in the room, in silence, at the start of the meeting. That genuinely works. It also spends twenty to thirty minutes of everyone's time every single time, and my read is that it works because the surrounding culture already holds the document to a standard.

You don't have that standard yet. Cancelling is how you buy it — and it isn't free. You lose a week, and the second time somebody senior asks why you couldn't just walk the room through it. Have the answer ready: because last time we did that, we shipped a 200 OK with no failure path behind it.

Running the Room — When You Also Wrote the Doc

Facilitating and defending are two jobs, and you will do both badly if you try to do them at once. If there's anyone else available, hand them the clock and the agenda and let yourself be a participant.

On a small team there usually isn't anyone else. The fallback is unglamorous and it works: say which hat you're wearing out loud when you switch. "Answering as the author: yes, that's a real gap. Back to facilitating — who else has something on the scan path?"

Start with the written objections, in the order they arrived. Not a walkthrough from slide one. The walkthrough is the default because it feels like respect for the work. It burns fifteen minutes on material everyone was supposed to have read, and it puts you in presentation posture — the posture where objections don't get raised.

Forty-five minutes. Set it before you start.

At minute forty, whatever is still open gets a name and a date rather than a resolution. This is the part first-time facilitators find hardest, because a live disagreement between two good engineers is genuinely interesting and it feels destructive to stop it. Stop it anyway. Two people can finish that argument in a room of two.

The exception worth making is when the open disagreement blocks the whole design — then extend once, deliberately, and say out loud that's what you're doing.

Here's the thing nobody tells you about running your first one: you're better at it than the person who has run thirty. Not more knowledgeable — better at the specific job. Thirty reviews in, an author has built a reflex to defend, and that reflex is what wrecks these meetings. You haven't built it yet.

Use the window while you have it.

The Output Is a Ledger — Not an Approval

The review ends and something leaves the room. If that something is minutes, or a status of "approved," you held a meeting about a design and changed nothing.

Zero objections isn't a clean review. It's a review that didn't happen.

What should leave is a short list where every row has four things: the objection, an owner, a date, and whether it blocks the merge.

That last column is load-bearing. Without it, every objection becomes a launch blocker, the format earns a reputation for stopping work, and people quietly stop raising things.

Google's SRE entrance reviews handle this explicitly — the review produces a prioritized list of issues, most of them assigned back to the development team, with a clear note that not everything on the list blocks the handover. Some findings are months of work that shouldn't hold up a launch. They still get written down, with a name on them.

The upload design left with three rows.

• Scan fails after the client got a 200 OK — owner: me, closes before merge. Blocking. The design had no failure path at all, which is why nobody had noticed it was missing.
• Bucket lifecycle deletes legal records at ninety days — owner: the storage engineer who raised it, closes this sprint. Blocking.
• No cost ceiling on the scanning service — owner: nobody. Not blocking.

That third row is the most useful thing the review produced, and it produced it by failing to find an owner. Nobody could say whose budget the scan came out of, which meant the service crossed a team boundary the design document hadn't acknowledged. An objection with no owner isn't an objection you can close. It's a finding about the org chart, and it gets escalated rather than assigned.

A row closes three ways: a decision, a spike with a return date, or an explicit accept-the-risk with a name attached. That third one is a real outcome and not a cop-out — as long as somebody's name is on it. On the upload design: a decision on the failure path, a dated spike on the lifecycle policy, and no third thing, because nobody was available to accept the cost risk.

Where the ledger goes afterward is your team's business. If you keep decision records, the closed rows are the raw material for one.

When It Was Never a Review — Three Fakes and One Legitimate Skip

Some meetings with "architecture review" in the title are not architecture reviews. Run one as though it were and you've volunteered to be responsible for the outcome.

The presentation with a quorum. No pre-read, no written objections, an author with slides. The room's job is to look attentive. Name it before it starts: ask whether anyone has read the document, and if the answer is no, you're back at the cancel rule.

The ambush. The design gets shown for the first time in the room, in front of the person most likely to kill it, so that it can be killed there. You'll know it by the invite list. Decline.

The already-decided. The choice was announced last week and this meeting exists to manufacture consent. There's nothing wrong with a meeting that explains a decision — there's a great deal wrong with calling it a review. Ask what the actual ask is. Sometimes the honest answer is "we want people to understand why," and that meeting is worth having under its real name.

Those three are fakes. The fourth is the legitimate one — the review you shouldn't hold at all. Reviews are a real trap of overhead, and waiting for a slot on a recurring calendar can stall a piece of work for a week. If the objections you're expecting can be settled in comment threads on the document, settle them there.

Book the room when the objections need to argue with each other in front of witnesses.

---

Run it as a ledger and the meeting gets a success condition you can check: you leave with rows that have names and dates on them. The design ends up different from the one you circulated on Monday.

So — what's the objection you wish someone had written down before your last design shipped? Did anyone ever put a name against it?

Bring the row, not the retrospective.