Topic: RFC-to-ADR process
The RFC-to-ADR Process — How Engineering RFCs Become Architecture Decision Records
An RFC (Request for Comments) is the consultation layer before a decision. An ADR (Architecture Decision Record) is the durable record after a decision. The two formats are sequential, not competing: the RFC opens the conversation, surfaces objections, and builds shared context; the ADR closes it with a record that future engineers can trust. This page covers the RFC lifecycle stages, the review ceremony, how RFC sections map to ADR sections, and the failure modes that cause RFC processes to produce no useful record at all.
TL;DR
Every accepted RFC should be closed with an ADR written by the RFC author. The RFC's problem statement becomes the ADR Context; the RFC's proposed solution becomes the ADR Decision (condensed to one active-voice sentence); the RFC's alternative approaches become the ADR Alternatives Considered; the RFC's acceptance commitments become the ADR Consequences. The most common failure is running the RFC process without naming a decision-maker, so the RFC never closes and no ADR is ever written. Set a review deadline, name a closer, and write the ADR before the RFC author forgets which trade-offs came up in comments.
What the RFC process adds that writing an ADR directly does not
Writing an ADR directly — without an RFC stage — is appropriate for decisions made within a single team with no external stakeholders. The author writes the decision, one or two reviewers approve it in a PR, and the ADR is merged. This works well and should be the default for most decisions.
The RFC process adds a consultation layer for decisions that cross team boundaries, establish org-wide patterns, or affect external API consumers. Three things the RFC stage produces that a direct ADR does not:
- Shared context before the decision point. Engineers who will be affected by the decision have an opportunity to flag constraints the RFC author didn't know about. The RFC author may not know that Team B has a dependency on the API being redesigned. The RFC comment period surfaces that dependency before the ADR records a decision that commits Team B without their input.
- A richer Alternatives Considered section. When stakeholders comment on an RFC, they frequently propose alternatives the author hadn't considered. These alternatives — even the ones ultimately rejected — become the most valuable part of the ADR for future engineers who face the same decision. An ADR written directly from the author's head often has a thin Alternatives Considered section ("we considered X but chose Y for Z reason"); an ADR written after an RFC comment period has the actually-considered alternatives, including ones that sounded good initially and were rejected for specific reasons.
- Audit trail of who was consulted. For decisions with compliance implications (data model changes, external API deprecations, security architecture) an RFC with a named stakeholder list and a recorded decision provides the governance audit trail that a direct ADR cannot. The RFC header names who was consulted; the ADR records who made the decision. Together they satisfy the "who approved this" question that auditors and incident retrospectives ask.
The cost is latency. An RFC process adds 1–4 weeks to the decision timeline. For decisions where that latency is acceptable (no active incident, no critical-path blocker), the RFC produces better ADRs. For decisions where it is not acceptable, skip the RFC and write the ADR directly.
The RFC lifecycle: five stages
Most engineering RFC processes (borrowing from Rust, Python, Django, and Kubernetes) converge on five stages:
Stage 1 — Draft
The RFC author opens a pull request in the RFC repository (or a doc in Confluence, or a Google Doc, depending on the org's chosen medium) with the proposed change. The document is marked Draft or Proposed. The author typically notifies affected stakeholders directly in addition to the PR/doc notification. During the Draft stage, the author may revise the RFC freely based on early feedback before the formal review window opens.
Stage 2 — Under Review
The RFC is marked Under Review and the comment window opens. The review window duration should be set in the RFC header and announced to stakeholders. Standard norms: 1 week for squad-scoped decisions, 2 weeks for org-wide, 4 weeks for cross-org or externally-visible. During Under Review, the RFC body may be revised to incorporate feedback that improves the proposal — but substantive changes should be marked clearly (e.g., inline diff comments or a revision log at the bottom) so late reviewers can see what changed.
Stage 3 — Final Comment Period (FCP)
When the decision-maker judges that the RFC is ready to close, they announce the Final Comment Period — typically 7 days — during which previously-silent stakeholders have a last opportunity to raise objections. The FCP announcement is a forcing function: it converts passive non-review into active sign-off. After FCP closes, the decision-maker proceeds to Stage 4. Skipping the FCP is acceptable for small-scope decisions; teams with high review participation may not need the FCP step.
Stage 4 — Decision
The named decision-maker closes the RFC with one of three outcomes: Accepted, Rejected, or Withdrawn (author pulls the RFC). The decision comment should record the decision-maker's name and the date. If the RFC is rejected, the decision comment should record the reason — this becomes the Consequences section of the rejection ADR. The RFC PR is then merged (with the decision recorded in the RFC header) or closed without merging (for Withdrawn).
Stage 5 — ADR Written
The RFC author (or the named decision-maker, if different) writes the ADR from the accepted RFC. The ADR date is the Stage 4 decision date, not the ADR commit date. The ADR PR should reference the RFC PR number in the description so the two records are linked in version control history. Once the ADR is merged, the RFC is complete.
The review ceremony: who reviews, who closes, and how to prevent RFC gridlock
The review ceremony is where RFC processes most commonly fail. Two failure modes dominate:
Failure mode 1 — No named decision-maker
If the RFC can only close by consensus, it will not close. In most engineering organizations, consensus across all affected stakeholders on architectural decisions is unattainable — there will always be a dissenting voice with a legitimate concern that cannot be fully satisfied. Without a named decision-maker with the authority and willingness to close over a dissent, the RFC sits open indefinitely. The fix is simple but requires organizational will: every RFC must name a decider: in the header. The decider may accept the RFC over a documented dissent. The dissent is recorded in the RFC; the ADR records that the dissent was heard but the decision was made anyway.
Failure mode 2 — Reviewers who were consulted but not notified
An RFC review period with no actual engagement is a rubber stamp, not a consultation. The RFC author must notify affected stakeholders directly — a PR notification in a GitHub repo is insufficient; engineers triage PR review queues and deprioritize RFCs for other teams' services. A direct Slack message, an @mention in the relevant channel, or a calendar event for a synchronous review meeting is required to actually surface the RFC to the stakeholders it affects.
Scalable review norms
- Squad-scoped decision (1–5 engineers affected): 1-week async PR review. Decision-maker: tech lead or senior engineer on the squad. No FCP required.
- Cross-squad decision (multiple teams, no external API): 2-week async PR review + optional 1-hour synchronous review meeting for complex trade-offs. Decision-maker: staff engineer or principal engineer. FCP optional.
- Org-wide pattern (establishes a default for all teams): 2-week async + mandatory synchronous review meeting. Decision-maker: principal engineer or architecture board. FCP required.
- External-facing change (API deprecation, third-party integration): 4-week review with external stakeholder notification. Decision-maker: engineering manager or VP Engineering. FCP required. ADR requires named Stakeholders field.
Mapping RFC sections to ADR sections
An ADR is not a copy of the RFC. The RFC is exploratory — it proposes, invites objections, and may change through multiple revisions. The ADR is declarative — it records what was decided, in one sentence, with honest trade-offs. The transformation from RFC to ADR should be a compression, not a copy-paste.
| RFC section | Maps to ADR section | Transformation note |
|---|---|---|
| Motivation / Problem Statement | Context | Condense to the forces that made the decision necessary, not the full problem narrative. 2–4 sentences max. |
| Proposed Solution / Design | Decision | Reduce to one active-voice sentence: "We chose X over Y because Z." The RFC's full design lives in the RFC; the ADR records the conclusion. |
| Alternatives Considered | Alternatives Considered | Include alternatives that came up in the RFC comment period, not just the ones the author pre-considered. This is the ADR's most valuable section for future readers. |
| Acceptance Criteria / Success Metrics | Consequences (positive) | Copy the commitments the RFC made — these are what the team agreed to accept when they approved the RFC. |
| RFC comment thread — dissents and risks raised | Consequences (negative) | The most commonly omitted source for the Consequences section. Dissenting comments in the RFC PR are the honest downsides the decision-maker accepted anyway. |
| RFC header: decider, date, stakeholders | ADR frontmatter: decider, date, stakeholders | The decision date is the RFC Stage 4 date. The decider field identifies who had authority to close. Reference the RFC PR number in the ADR's Supersedes or see-also field. |
One section the RFC typically does not produce directly: the ADR Status history. The Status field ("Proposed → Accepted → Superseded") is maintained on the ADR itself, independent of the RFC lifecycle. The RFC being accepted is the event that sets the ADR's initial Status to Accepted.
When to skip the RFC and write the ADR directly
Four conditions under which skipping the RFC is the right call:
- The decision is fully reversible. If the decision can be undone in a single PR with no data migration, no external API change, and no downstream breakage, the RFC overhead is not warranted. Write the ADR, get two approvals, ship. Use the ADR review checklist to verify the scope.
- All affected stakeholders are in the same room. If the decision affects exactly one squad and every engineer on that squad is in the synchronous design discussion, the RFC comment period adds no information the discussion didn't already produce. Write the ADR from the meeting notes the same day.
- The decision is time-critical. Security incidents, outage mitigations, and compliance deadlines don't wait 2 weeks for an RFC comment period. Make the decision, execute, and write the ADR within 48 hours of execution (the 48-hour fidelity window — beyond this, ADR prose reads as post-hoc rationalization, not contemporaneous record). If the decision requires ITIL emergency-change approval, follow the ADR-EC workflow instead.
- The decision is already effectively made. If the team is documenting a technical direction that was informally decided in a Slack thread or a 1:1 six months ago, writing an RFC now would be a retroactive consultation exercise — everyone knows the decision is fait accompli. Write the ADR with the actual decision date, note in the Context that the decision predated formal documentation, and close. A backdated ADR is more honest than an RFC that nobody takes seriously because the outcome is predetermined.
RFC format comparison — the engineering RFC vs IETF/PEP/Rust styles
Most engineering organizations don't need a formal RFC process modeled on IETF or Rust. The IETF RFC format (with its abstract, status of this memo, normative language requirements, and multi-year standards track) is designed for internet protocol standardization, not software architecture decisions. The Rust RFC format is rigorous but has a large cognitive overhead for a startup or a 50-person SaaS engineering team. A lightweight engineering RFC typically contains:
- Header: RFC number, title, status, date, author, decider, stakeholders, review-by date
- Motivation: Why this decision is needed now (the triggering force)
- Proposed solution: The specific approach being proposed
- Alternatives considered: At minimum 2-3 alternatives with honest trade-offs
- Drawbacks: Explicit list of negatives, risks, or unknowns — required, not optional
- Unresolved questions: Questions the RFC doesn't answer that will need follow-up ADRs
The Drawbacks section is the most commonly omitted section in engineering RFCs and the most valuable for future readers. A Drawbacks section that says "none" is a red flag — every architectural choice has trade-offs. If you can't articulate the drawbacks, you haven't thought about the decision carefully enough to close the RFC.
| RFC style | Overhead | Best for | ADR relationship |
|---|---|---|---|
| Lightweight engineering RFC | Low (1–3 pages) | Startups, scale-ups, squad-to-org-level decisions | Direct 1:1 — one RFC closes with one ADR |
| Rust RFC (rust-lang/rfcs style) | Medium (3–10 pages) | Open-source governance, cross-organizational standards | One RFC may spawn multiple ADRs (different teams implementing the standard) |
| Python PEP | High (formal document, BDFL/steering council) | Language specification, standard library | PEPs are closer to ADRs themselves (post-decision records) than RFCs |
| Kubernetes KEP | High (PRD + design doc + implementation plan) | Large distributed open-source projects with SIG governance | KEP includes both RFC and ADR stages; the graduation criteria serve as the ADR acceptance criteria |
The AI-deliberation layer for teams without a formal RFC process
Many teams — especially startups and small engineering organizations — run an informal RFC-equivalent in Claude.ai or ChatGPT rather than a formal RFC document. The pattern is common: an engineer opens a new chat, describes the architecture problem, and uses the AI to stress-test alternative approaches, surface constraints they hadn't considered, and draft the core trade-off analysis. The AI conversation serves the same function as an RFC comment period — it produces the Alternatives Considered section material and the honest Drawbacks that a formal RFC review would surface.
The problem is the same as the formal RFC problem: if the AI conversation isn't closed with an ADR, the reasoning lives only in the chat history. The engineer who had the conversation knows why the decision was made; the next engineer who inherits the codebase does not.
The WhyChose extractor is specifically designed to close this loop. It reads your Claude.ai or ChatGPT conversations.json export and surfaces the architecture decisions inside — the alternatives that were raised and rejected, the trade-offs the AI identified, the constraints the conversation uncovered. The extracted output provides the Alternatives Considered and Context sections for the ADR that should have been written when the decision was made. The RFC stage happened in the AI chat; the ADR stage is what WhyChose produces from it.
Related questions
Should every RFC produce an ADR?
Every accepted RFC should produce an ADR — the RFC opened the consultation; the ADR closes it with a durable record. A rejected RFC should produce an ADR only if the team will face the same decision again within 1–2 years, in which case recording why the approach was rejected prevents re-litigating the same ground. A withdrawn RFC (author pulled it before a decision) typically does not need an ADR since no decision was made. Teams that run RFC processes without closing them with ADRs produce governance artifacts that record the conversation but not the conclusion — exactly the gap WhyChose's extractor is built to surface when the reasoning lives in AI chat sessions rather than formal documents.
How long should the RFC review period last?
A practical norm: one week for decisions scoped to a single squad (fewer than five engineers affected, no cross-team API contracts), two weeks for decisions affecting multiple teams or establishing an org-wide pattern, four weeks for decisions affecting external API consumers or carrying compliance implications. The most critical factor is not the window length but naming a decision-maker who will close the RFC at the deadline. An RFC with no named closer stays open indefinitely — engineers assume someone else will pull the trigger.
What is the Final Comment Period (FCP) in an RFC process?
The Final Comment Period is a fixed window — typically 7 days — announced by the decision-maker to signal that the RFC is about to close. Previously-silent stakeholders have a last opportunity to raise objections before the decision is made. The FCP announcement converts passive non-engagement into a conscious decision to not object. After the FCP closes, the decision-maker accepts or rejects the RFC. The Rust RFC process (rust-lang/rfcs) codified this as a formal stage. In smaller organizations, a simple "closing in 48h unless objections" comment in the PR thread serves the same function without the overhead of a named stage.
Who should write the ADR after an RFC is accepted?
The RFC author or the named decision-maker — not a documentation team member acting as a scribe. The ADR author needs to be close enough to the decision to write the Consequences section with honest downsides, including the trade-offs raised as dissents in the RFC comment period that were accepted anyway. An ADR written by a scribe condensing the RFC text will omit these — they'll capture the RFC's promises but miss the accepted risks. The ADR date is the Stage 4 decision date, not the date the ADR file was committed to the repository.
Further reading
- ADR vs RFC — what's the difference and when should you use each? — the comparison page that covers when to use RFC, when to use ADR, and the key distinction (RFC = pre-decision, open, seeking input; ADR = post-decision, closed, preserving rationale). The RFC-to-ADR process page you're reading now covers the ceremony of that handoff; this page covers the conceptual distinction and the decision tree for which format to use when.
- The ADR review checklist — a 12-item PR quality gate — once the RFC process closes and the ADR is drafted, this checklist is the final quality gate before merge. Covers the Decision section completeness test (is it one active-voice sentence?), the Consequences section honesty test (does it name at least one negative?), and the traceability requirements (does the ADR reference the RFC and the PR that implements it?). The RFC-produced ADR should score clean on all 12 items.
- ADR adoption guide — introducing ADRs to a team that doesn't already have them — the RFC process is one path to getting a team to write ADRs; this guide covers the others, including the retrospective ADR backlog approach (writing ADRs for decisions that have already been made but are undocumented) and the PR-gate approach (requiring an ADR assessment comment on every large PR). RFC adoption and ADR adoption are separate questions; many teams run ADRs without RFCs and RFCs without ADRs.
- ADR template for ITIL change management environments — in regulated environments, the RFC-to-ADR process runs alongside ITIL Change Management. The CAB (Change Advisory Board) approval layer sits above the RFC review layer: the RFC addresses whether the architecture is sound (engineering question), the Change Record addresses whether the deployment is safe (operations question). This page covers the ADR-CM template that cross-references both layers, including the Emergency Change workflow when the time-critical condition applies and the RFC stage is skipped.
- When to write an ADR — the decision scope test — the counterpart to the RFC skip conditions on this page. While this page explains when an RFC adds value, the when-to-write-an-adr page establishes whether an ADR is warranted at all. A decision that doesn't meet the ADR threshold doesn't need an RFC either.
- ADR from meeting minutes — the no-RFC counterpart — the synchronous decision path that skips the RFC entirely. For decisions that meet condition 2 (all affected stakeholders are in the room) or condition 3 (time-critical), the RFC is skipped and the decision is made in a meeting. This page covers what to capture from the meeting that feeds the ADR: the 24-hour fidelity window, the verbal alternatives that only exist in meeting participants' memory, and the AI-assisted conversion workflow when a Zoom or Teams transcript is available.
- The open-source extractor — reads your Claude.ai or ChatGPT conversations.json and surfaces architecture decisions as structured ADR records. For teams that use AI chat as their informal RFC-equivalent deliberation layer, the extractor is the tool that turns those conversations into the ADR that should have been written when the decision was made.