The Document That Makes Disagreement Cheap

The subject is the RFC — a request for comments, also called a design doc or proposal. Its job is to make disagreeing with you cost a comment instead of a rewrite.

Notebook-style infographic: the required structure of an RFC, from problem and evidence through rejected alternatives to review deadline.

Core Concept

An RFC is a written proposal whose job is to move an argument out of people's heads and into one reviewable artifact — before the code exists. That is the whole trick. Disagreement is expensive when it arrives after the migration; it is cheap when it arrives as a comment on a paragraph. And for a practice topic like this one, the mechanism is the structure, not the sentiment. "Write things down and be collaborative" is a mood. A document with the required sections in the required order is a mechanism.

Key Components

Section 1–2

Problem, with numbers

State the problem and its evidence first — quantities, not adjectives. Then the constraints you must respect. A proposal that opens with its solution is asking for agreement, not review.

Section 3 — the load-bearing one

At least two rejected alternatives

Each with the actual reason it was rejected. A proposal with no rejected options is a decision already made, wearing a document as a disguise.

Section 4–6

Design, migration, and the falsifier

The proposed design, how you get there from here, and the part most authors omit: what would have to be true for this to be the wrong choice.

Section 7

An explicit review deadline

An open document is not a decision. Without a date, the doc becomes a permanent holding pattern that lets everyone avoid committing while feeling rigorous.

How It Works

Problem + evidence. Write what is broken and how much, with real quantities — latency, cost, error rate, hours lost. Numbers are what stop the debate from becoming a taste contest.
Constraints. Name the things you are not allowed to change: deadlines, compliance, an existing schema, a team that owns the other half. Reviewers who don't know the box will suggest options outside it.
Rejected alternatives — two minimum. For each, the real reason. Not "too complex" but "requires dual-writes for six weeks and we have no backfill window."
Proposed design. Now, and only now, your answer. It reads as a conclusion drawn from the sections above rather than a preference defended after the fact.
Migration path. The sequence from today's system to the proposed one, including the ugly intermediate state where both exist. This is where most designs actually die.
When this is wrong. Write the conditions that would falsify your own choice. This single section converts a pitch into an engineering document.
Review deadline. A date by which comments must land and the decision is taken. Then the argument has somewhere to end.

Where It Earns Its Keep

Schema and storage changes. The cost of being wrong is a migration, so the cost of a comment is trivially worth paying.
Cross-team interfaces. Two teams reading the same paragraph beats two teams remembering the same meeting differently.
Irreversible or expensive commitments — a vendor, a datastore, a protocol version. Reversible decisions rarely need a document; just make them and watch.
Onboarding, as a side effect. The rejected-alternatives section is the only place a newcomer can learn why not, which is most of the institutional knowledge in any codebase.

Falsification — Read This Twice

Where the practice fails

Writing more documents does not produce better decisions. An organisation that requires an RFC for everything gets design paralysis and a graveyard of unread drafts.

Worse, the ritual becomes cover: a document that survived review is treated as validated when in fact nobody actually read it. Silence gets recorded as consensus. The doc then protects the decision from scrutiny rather than exposing it — the exact inversion of its purpose.

Test the process, not the prose

Don't grade RFCs on how well they are written. Measure whether review changes anything:

materially_changed_by_review
  = proposals whose DESIGN changed after comments
  ÷ proposals reviewed

near zero  →  review is theatre;
             the deadline is doing all the work

Checkpoint — answer before you move on

Why is a proposal with no rejected alternatives structurally suspect, regardless of how well the proposed design is argued? Hint: what does the absence of options tell you about when the decision was actually made?
An RFC has been open for five weeks, has eleven approving comments and no objections. Name two different states of the world that produce that exact signature, and the one measurement that separates them. Hint: one world has real consensus; the other has readers who skimmed. Count material changes, not approvals.
Your team mandates an RFC for every change. Six months in, throughput is down and drafts are piling up unread. What is the correct correction — better templates, or a narrower trigger? Justify with the cost-of-being-wrong criterion. Hint: reversible, cheap-to-undo decisions do not repay the document.

One practice for this week: take a decision you have already made in your head — a refactor, a library choice, a schema change — and write only section 3 and section 6: two alternatives you rejected with the real reason, and what would have to be true for your choice to be wrong. If you cannot fill either section honestly, you have found the weak part of the decision, not the weak part of the exercise.