Getting the disagreement out early

You have a design doc with three options in it and a recommendation that names its own cost. Now it has to survive other people, which is the entire reason you wrote it as a decision rather than a description.

This is the shortest lesson in the course and the one people most often get wrong, because the failure mode does not feel like a failure. It feels like being thorough.

Circulating: give reviewers a job

The default is to post the link and write “any thoughts?” This reliably produces one of two outcomes: silence, or a comment about formatting. Neither is the reviewer’s fault. You handed them a document and no task, and reviewing a whole design well is expensive enough that most people, given no direction, will spend nothing.

Direct the attention instead. Say where you are least sure, and be specific enough that answering is cheap:

“I’d most like eyes on the buy-versus-build call in section three. I think the per-connection cost is acceptable up to about forty customers, and I’m least confident in that threshold — if you think it’s wrong, that changes the recommendation.”

Naming your own weakest point feels like handing someone a stick to hit you with. It is the opposite: it is the difference between a review that finds the flaw now and one that finds it after you have built for three weeks. It also signals that you actually want review, which is rarer than people admit and which reviewers can tell.

The comment you get tells you which document failed

Here is the idea worth taking from this lesson. When the comments arrive, read them first as a diagnostic — not of the design, but of your own earlier work.

They are arguing about the problem

Someone says “wait, why are we doing this at all?” That is not a design comment. It means your framing never landed — the one-pager either was not read or did not convince, and you have been building on agreement you did not have. Stop the design conversation and go back to the problem. Continuing to defend the design here is arguing about the roof with someone who disputes the foundations.

They are arguing about whether it is worth doing now

A weaker version of the same thing, aimed at your why-now. Usually it means the urgency you asserted was not evidenced — you wrote a number nobody checked, or you wrote none.

They re-propose an option you already considered

“Have we thought about just doing JIT provisioning?” Your alternatives section either is not there, is too thin, or is below the fold. This is the cheapest failure to fix and the most common: you did the work and buried it. Reviewers do not read to the bottom.

They are arguing about implementation detail

Which library, what the table looks like, how to structure the handler. This is what success looks like. An argument about detail means the problem, the urgency and the decision have all been accepted, and the conversation has moved to the part where their expertise is most useful.

Responding without defending

Every comment is one of two things, and the whole skill is sorting them before you reply:

• “You misread the doc.” The reviewer reached a wrong conclusion about what you wrote. This is a defect in the document, not in the reviewer. Fix the document. If one careful person misread it, several less careful people already have and did not say so.
• “You disagree with the decision.” They understood you perfectly and think you are wrong. This is the thing you circulated the doc to find. Engage with it properly, which usually means asking what they would trade rather than restating your reasoning louder.

The reflex to resist is explaining. When a comment lands, the instinct is to reply with why you are right — and if the comment was type one, the explanation belongs in the doc, not in a thread where only one person will see it. A design doc that needs a person attached to it in order to be understood is not finished.

Closing it: disagree and commit

Threads do not end on their own. Left alone they either run until everyone is tired, or they go quiet in a way that looks like agreement and is not — and the unresolved disagreement surfaces again in six weeks, usually at the worst moment.

The principle for ending them is disagree and commit, usually credited to Andy Grove at Intel and formalised by Amazon as a leadership principle. The point is that consensus is not the bar. Waiting for it produces the consensus trap, where the absence of agreement becomes the absence of a decision, and nothing happens while everyone stays technically blameless (Bezos, 2016 letter to shareholders).

It is a two-sided contract, and both sides are load-bearing. You get to argue hard, including with people senior to you, and to have that argument taken seriously. And once the decision is made, you commit for real — you do not relitigate it in three weeks, and you do not tell people afterwards that you were against it. Half of that contract without the other half is either a rubber stamp or a grudge.

Write down what was decided

The last step takes two minutes and saves the thread being re-run. Record the decision, its context, and its consequences somewhere dated and immutable — which is exactly what an ADR is for, and why the glossary has been carrying that term since the design-doc lesson.

The value is not bureaucratic. In three months somebody — possibly you — will ask why the project is paying a per-connection fee instead of having built it. Without a record, that question restarts the whole argument with none of the original context and a fresh cast. With one, it takes thirty seconds: here is what we knew, here is what we chose, here is what we said we would revisit and when.

Now apply it: run the review

What this does not cover

The decision has survived contact with other people, which means it is real enough to put a number on. That is next: how long it takes, how confident you are in that, and why the honest answer is a range rather than the single number everyone is about to ask you for.