RepoSCALE-SPECIFICLIFETIME-SPECIFICCONTESTED

RFCs

Problem, Goals, Non-Goals, Design, Alternatives, Risks, Rollout, Open Questions. A written proposal for decisions too large for a meeting — and a reliable source of theatre when applied to decisions that are not.

Constraints & invariantsWho owns whatWhat the next change costs

The requirement, the obvious build, and why it breaks

Every lesson starts where the work starts: someone asked for something, and the first implementation that comes to mind survives until the requirement changes.

The question

When is a written proposal worth more than a conversation, and how do I tell whether our RFC process is producing decisions or documents?

The requirement

The team wants to replace the background job system. It affects six teams, has three plausible approaches, and the decision will be lived with for years. A meeting is not going to settle it.

The obvious build

RFCs are how serious engineering organisations make decisions. Write one for any significant change, circulate it, collect comments, and you have alignment.

Why it breaks

"Any significant change" has no boundary, so the volume grows, and the RFC that genuinely needed five careful readers gets the same skim as the one about a folder rename.

How it breaks as requirements change
  • "Any significant change" has no boundary, so the volume grows, and the RFC that genuinely needed five careful readers gets the same skim as the one about a folder rename.
  • Comments are not a decision procedure. Without a named decider and a deadline, an RFC accumulates suggestions until the author gives up or quietly implements it anyway.
  • The cost lands entirely on the author, which selects for people who enjoy writing rather than for the best proposal, and it makes proposing expensive enough that people stop.
  • Once the process exists, it acquires a second use: as a way to be seen doing rigorous engineering. That version is indistinguishable from the real thing until you check whether any RFC has ever been rejected.
  • And it can genuinely slow the thing it is meant to improve. A two-week RFC cycle for a decision that is cheap to reverse costs more than being wrong (Reversible and Irreversible Decisions).
Requirement→Constraints→Invariants→Responsibilities→Boundaries→Interfaces→State→Dependencies→Failure→Implementation→Tests→Feedback→Evolution

What limits the solution, and what must never stop being true

This domain leads with these two. A design that ignores its constraints is not a design, and an invariant nobody named is one nothing is protecting.

Constraints
  • The people who need to weigh in are in four timezones, so a synchronous decision is a scheduling problem before it is a technical one.
  • Writing it costs the author several days, and reviewing it costs everyone else an hour each — a real budget that must be justified by the decision's size.
  • Whatever is decided has to be findable in two years by someone who was not there (Decision Records).
Invariants
  • Every RFC ends in a state: accepted, rejected, superseded or withdrawn. An RFC with no terminal state is a document, and documents do not decide anything.
  • Non-Goals are as binding as Goals. An unbounded proposal cannot be evaluated, because any objection can be answered with "we could also do that".
  • Objections raised and overruled are recorded with the reason, or the decision cannot be revisited honestly (Revisit Triggers).

Who owns what, and where the seams fall

Responsibilities decide boundaries; boundaries decide what an interface has to say.

Responsibilities
  • The author owns the problem statement and the alternatives, including the strongest form of the option they are not recommending.
  • A named decider owns closing it — accepting, rejecting or sending it back — by a stated date. Without this role the process has no terminal state.
  • Reviewers own reading it and objecting substantively; a comment on wording in a document about job systems is noise (Tone, Disagreement and Receiving Review).
  • The team owns the threshold: which decisions warrant an RFC. Keeping that list short is what keeps the mechanism credible (The Complexity Budget).
Boundaries
  • The boundary between RFC and design review is synchrony and audience: a meeting works when the right people can be assembled and share context; an RFC is what you use when they cannot (Design Review).
  • The boundary between RFC and decision record is direction: an RFC argues toward a decision, a record documents one that has been made. The RFC becomes the record when it is accepted (Architecture Decision Records).
  • The boundary between RFC and specification is that an RFC is about the choice. Once the choice is made, the implementation detail belongs in the code and its tests, not in a document that will drift (Documentation Decay).

Eight sections, in a thinking order

The template is not a form. Each section constrains the next, which is why the order matters and why jumping to Design is the failure that produces unevaluable proposals.

The two sections most often written badly are Non-Goals and Alternatives, and they are the two that determine whether a reader can disagree usefully. A proposal with no bounds and no rejected options cannot be argued with, only approved.

The template, with the failure that each section prevents
1RFC-014  Replace the background job system
2Author:  ...        Decider: ...        Decide by: 2026-09-15
3Status:  Draft | In review | Accepted | Rejected | Superseded
4 
51 PROBLEM     What is wrong today, with evidence. Not "the current
6              system is old" — "17 incidents in 6 months, all from
7              silent job loss on redeploy".
8              Prevents: solving a problem nobody has.
9 
102 GOALS       What must be true afterwards, testably.
11              Prevents: success that cannot be assessed.
12 
133 NON-GOALS   What this deliberately does NOT address.
14              Prevents: an unbounded proposal, where any objection
15              is answered with "we could also do that".
16 
174 DESIGN      The proposal. Interfaces, ownership, state, data.
18              Prevents: agreement on a direction that turns out to
19              be two different designs.
20 
215 ALTERNATIVES  Each option's strongest form, and why not.
22              Prevents: a decision that was made before the
23              document was written.
24 
256 RISKS       What could go wrong, including the failure of the
26              mitigation, and what we would do about it.
27              Prevents: risk discovered during rollout.
28 
297 ROLLOUT     How we get from here to there while running.
30              Migration, intermediate state, and the way back.
31              Prevents: a design that cannot be adopted.
32 
338 OPEN        What is undecided, and who decides it.
34              Prevents: false consensus.
35 
36DECISION      Filled in on close: what was decided, what was
37              overruled and why, and the revisit trigger.

Section 8 is the health indicator for the whole document. An RFC with no open questions is either trivial or has stopped thinking, and reviewers should treat an empty Open section as the first thing to ask about. The DECISION block at the bottom is what turns the RFC into a decision record on acceptance, so there is no second document to write (Architecture Decision Records).

From draft to decided, including the states people avoid

The reason RFC processes stall is almost never disagreement. It is that no state transition is anyone's job: a document sits in review, comments accumulate, and there is no defined moment at which it becomes something else.

Two of the transitions below are the ones organisations quietly remove, and removing them is what converts the process into a publication channel.

The life of an RFC
DraftIn reviewAcceptedRejected ·Withdrawn ·Superseded ·
FromOnToGuardEffect
DraftThe author circulates itIn reviewA decider and a decision date are named on the first lineReviewers are asked for a specific window of attention
In reviewReview reveals the design needs reworkDraftThe author intends to bring it backComments so far are summarised, so the second round does not restart
In reviewThe decider closes itAcceptedOpen questions are resolved or explicitly deferred with ownersDECISION block filled in; linked from the code that implements it
In reviewThe decider closes itRejectedThe reason is recorded and is about the proposal, not the authorKept in the repository — a rejected RFC is the cheapest way to stop the idea recurring annually
In reviewThe author stops pursuing itWithdrawn—A one-line note on why, which is often the most useful sentence in the document
AcceptedA later RFC changes the decisionSupersededThe later RFC exists and is acceptedForward pointer added; original text left intact
must be impossible
  • Draft → Accepted — Skipping review makes the process a publication channel. It is the most common shortcut in organisations where the RFC is written after the work has started, and it converts the mechanism into documentation of a decision nobody was allowed to influence.
  • Accepted → Draft — Editing an accepted RFC to match what was actually built destroys the record of what was decided and why, which is the entire asset. If reality diverged, supersede it — an outdated document with a forward pointer is far more useful than an amended one that pretends it was always right (Documentation Decay).
  • Rejected → Accepted — Reopening the same document after a rejection re-runs the argument with none of the new evidence visible. A changed mind deserves a new RFC that cites the old one, so a reader can see what changed.
  • In review → In review — Indefinite review with no decision date is the state most RFCs actually die in, and it is worth naming as forbidden because nobody ever chooses it. The date on the first line exists precisely to make this transition impossible.

A process where nothing has ever reached Rejected is not a process with unusually good proposals. It is a process where the decider role does not really exist, and the fastest diagnostic available is to count the rejections.

When the process has become theatre

CONTESTEDThere is a defensible position that a hundred per cent acceptance rate is fine and the rejection test is a bad metric: proposals should be socialised informally before they are written, so by circulation time the disagreement has already been resolved and the document genuinely is a record. Organisations that work this way argue that public rejection is wasteful and demoralising. The counter is that informal socialisation is invisible to everyone outside the author's network, which quietly makes the process work well for insiders and badly for everyone else.

This is worth naming as a smell rather than as a rule, because the healthy and unhealthy versions produce identical artefacts. The same template, the same circulation, the same comment threads — and one of them decides things.

The honest position is that most RFC processes drift into this state, not because anyone chose it, but because every incentive points that way: writing one is visible work, rejecting one is socially expensive, and adding a section is easier than removing one.

smellDecision theatreThe RFC that documents a decision already made

looks like Every RFC is accepted. The Alternatives section describes each rejected option in one dismissive sentence. Non-Goals says "none" or is missing. Comments are about wording, formatting and section completeness rather than about the choice. The implementation was underway before circulation, and the RFC's merge commit is later than the first implementation commit.

suggests The process has become a publication channel with an approval ritual attached. Its real function is legitimising decisions rather than making them, which is worse than having no process: it consumes reviewer attention, it teaches everyone that objecting is pointless, and it produces a false record that a future engineer will read as evidence that alternatives were seriously weighed (Documentation Decay in its most expensive form, because the document is not merely stale but was never true).

fix Do not add process. Change two things: name a decider with the standing to reject, and require the Alternatives section to state the strongest form of each option — the version its advocate would recognise. Then circulate before implementation starts, not after. If the acceptance rate does not move within a few months, the honest conclusion is that this organisation makes its decisions elsewhere, and the correct response is to shrink the RFC to a five-line decision record and stop pretending (Decision Records).

when this is fine When the RFC is deliberately a record of a decision the team has already reached together — a small team that argued it out at a whiteboard and is writing it down for people who will join later. Then the acceptance rate of one hundred per cent is honest, the alternatives really were dismissed in conversation, and the document is doing exactly the job it claims. This case looks identical from the outside and is distinguished by one question: was there a moment at which this could have gone the other way, and did the people affected have access to that moment?

How to build it

Most important first.

  • Use the eight sections and keep them in order: Problem, Goals, Non-Goals, Design, Alternatives, Risks, Rollout, Open Questions. The order is a thinking order, and skipping to Design is the characteristic failure.
  • Write Non-Goals honestly and early. They are what make the proposal evaluable, and they are the section that most often reveals the author has not decided what they are doing (Requirements Before Design).
  • Make Alternatives real. An alternative described in one dismissive sentence tells the reader the decision was made before the document was written, and it destroys the credibility of everything above it (The Trade-off Matrix).
  • Name a decider and a date on the first line. This single change is the difference between a process that produces decisions and one that produces documents.
  • Set a threshold and defend it: cross-team, expensive to reverse, or long-lived. Everything else gets a conversation or a design review (When Design Does Not Pay).
  • Keep the accepted RFC in the repository, linked from the code, with its status and its revisit trigger. An RFC in a wiki is a decision you will not find in two years (Docs Close to Code).

What the next change costs

The field this whole domain exists for. A structure is only better if it makes the change after this one cheaper — and it is worth saying which changes it does not help.

Cost of the next change
  • Writing one: two to four days of the author, plus an hour each from five to fifteen reviewers, plus one to two weeks of elapsed time. That is the price, and it is only justified when the decision is expensive to reverse.
  • Not writing one for a decision of that size: the decision is made implicitly by whoever writes the first module, and the six affected teams discover it during integration (Change Amplification).
  • Writing one for a small decision: the same two to four days, spent on something a fifteen-minute conversation would have settled. Repeat this a few times and the team stops proposing anything (Over-Design and Under-Design).
  • The compounding return is on the *next* decision in the same area: an accepted RFC with recorded alternatives means the argument does not restart from zero when the requirement shifts, which is worth more than the original decision in a long-lived system.
What the recommended approach costs
  • Writing costs days of the author and buys a decision that survives them. For a decision that will not be lived with for years, that is a bad trade and it is made constantly.
  • Asynchronous review reaches more people and loses the thing a meeting is good at: the fast back-and-forth that turns a vague objection into a specific one.
  • A named decider makes the process terminate and makes it political, because a rejection is now attributable. Consensus avoids that and pays for it by never deciding.

What can go wrong

Failure modes
  • No RFC has ever been rejected. The process is a publication channel, and its main output is the appearance of rigour.
  • The template becomes a form. Sections are filled to be complete rather than to think, and Non-Goals says "none" — which is the single clearest signal that the proposal has not been bounded.
  • The threshold erodes until an RFC is required for small decisions, at which point good engineers implement first and write the RFC afterwards, which is both rational and the end of the process.
  • An RFC is accepted and the implementation diverges from it, and neither is updated, so the document is now confidently wrong about a system people depend on it to explain.
  • The mitigation fails in its own way: adding a required approval quorum turns the deadline into a blocker, and work stalls waiting for a fourth reviewer who is on holiday.
Dependencies, and their direction
  • The process depends on a decider with the authority to reject. Without that, it depends on consensus, and consensus processes converge on the least objectionable option rather than the best one.
  • It depends on reviewers having enough context to evaluate the proposal, which is why RFCs written for an audience that has never seen the system have to carry their own background and are therefore long.
  • It creates a scheduling dependency for the work it governs, so the cycle time of the process becomes the floor on how fast a big decision can be made.
Misreads
  • "RFCs are how mature organisations decide." Some mature organisations decide well in meetings and record the outcome in five lines. The written form is a response to scale and asynchrony, not a marker of seriousness (When Design Does Not Pay).
  • "More sections means more rigour." Each additional required section lowers the quality of every other one, because the author's attention is fixed. Twenty sections produce twenty shallow ones.
  • "The RFC is the design." It is the argument for a choice. The design lives in the code, and the moment they disagree the code is right and the RFC needs a status change (Documentation Decay).
  • "Comments mean engagement." Fifty comments on wording and none on the alternatives means nobody evaluated the decision. Volume and engagement are close to unrelated.
Smells this explains
  • speculative-generality

Testing it, and how it ages

What to test, and at which boundary
  • The rejection test: has any RFC been rejected or substantially changed by review in the last year? If not, the process is theatre and should be either fixed or stopped.
  • The findability test: can someone who joined last month find the reasoning behind the current job system in under five minutes? That is the only durable value an RFC produces.
  • The drift test: does the accepted RFC still describe what was built? If not, mark it superseded rather than editing it — an amended history is worse than an outdated one.
How this design ages
  • RFC processes reliably become heavier over time, because every failure produces a new required section and nothing ever removes one. The template is a good proxy for the health of the process: eight sections is a thinking tool, twenty is a form.
  • The audience broadens as the organisation grows, so RFCs get longer to carry context, so fewer people read them fully — and past a certain size the honest response is a one-page summary at the top rather than more sections.
  • A mature process eventually distinguishes tiers: a lightweight one-pager for reversible decisions and a full RFC for the rest. Teams usually arrive at this after the threshold has already eroded once (Revisit Triggers).

Where this applies

This domain's advice is contested more than most. These labels say what each claim is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view rather than a caricature.

  • SCALE-SPECIFICBelow roughly twenty engineers in one or two timezones, an RFC process is almost always net negative: the people who need to agree can be assembled, a whiteboard plus a five-line decision record does the same job in an afternoon, and the writing cost suppresses proposals. It starts to pay when the affected people cannot be assembled — multiple timezones, five or more teams, or a decision whose reviewers include people who will join later. At several hundred engineers it is close to unavoidable for anything cross-cutting, and the design problem shifts to keeping the template short and the threshold high. Adopting the large-organisation process at fifteen engineers is one of the most effective ways to stop a small team proposing anything at all.
  • LIFETIME-SPECIFICThe main return on an RFC is that the reasoning survives the people, which is worth a great deal for a system that must live a decade and almost nothing for one being replaced next year. For short-lived work the same information is better carried by a paragraph in the pull request, where it costs minutes and is read by the people who need it.
  • CONTESTEDThe strongest opposing view, and it is held by serious practitioners: RFC processes are a bureaucratic response to a trust problem, and they degrade decision quality by rewarding writing over judgement and by giving every stakeholder a veto they have not earned. The proponents of this view point out that the best technical decisions in many organisations were made by two people at a whiteboard, and that the RFC arrived afterwards to legitimise it. The counter is that undocumented decisions are unavailable to everyone who was not in the room, including everyone who joins later, and that the cost of re-deriving them compounds — but the objection about veto creep is real and any healthy process has to answer it explicitly.

Where the depth lives

This domain teaches the codebase-level structure and hands the rest off.

Architecturewhat-is-software-architecture
DevOpschange-managementproduction-readiness-review
Domains that do not exist yet
  • — System Design — the decisions that most justify an RFC are usually system-level ones (a queue, a storage engine, a consistency model), where the alternatives differ in operational cost rather than in code structure, and that comparison belongs to System Design.