Writing RFCs That Unblock Engineering Decisions

Most teams do not fail because nobody had an idea. They fail because the idea never became a decision with owners, constraints, and a date. Request for Comments (RFC) or design-doc culture exists to turn fuzzy intent into something a staff engineer, product lead, or security reviewer can respond to in writing. When RFCs work, they replace recurring status meetings with async clarity. When they fail, they become long essays that nobody reads until code is already in production.

This post is for senior ICs and tech leads who need alignment on architecture, data models, or cross-team contracts—not for process theater. It connects to how you ship product on this site: from tickets to outcomes, TypeScript contracts across the stack, and portfolio-to-product credibility when your RFC affects what customers see.

What an RFC is for (and what it is not)

An RFC is a proposal, not a spec carved in stone. Its job is to:

• State the problem in language PM and engineering both recognize.
• Name options—including “do nothing for now.”
• Recommend one path with explicit tradeoffs.
• List open questions that block implementation.
• Request decisions from named roles by a date.

It is not a place to prove you read every paper on distributed systems, nor a substitute for a threat model when data crosses trust boundaries. Google’s engineering practices emphasize small, reviewable changes and clear ownership; design docs extend that mindset to changes too large for a single PR thread.

If your org already uses ADRs (Architecture Decision Records), an RFC can feed the ADR once the decision lands. Keep one canonical doc per decision; link out to spikes and benchmarks instead of pasting them inline.

Structure that gets responses

Readers skim under time pressure. A structure that consistently earns comments:

1. Summary — Three to five sentences: problem, recommendation, what you need from readers this week.
2. Context and goals — Who is affected, success criteria, non-goals (“We are not rebuilding billing.”).
3. Current state — Enough diagram or narrative that a new teammate understands why change is needed.
4. Options — At least two real alternatives; straw-man “rewrite everything” counts only if someone actually advocates it.
5. Recommendation — Why this option wins on cost, risk, and time; what you are accepting as debt.
6. Rollout and observability — Flags, migration steps, how you will know if you were wrong.
7. Open questions — Numbered; tag @handle for owners.

Use headings for scanability. Prefer one architecture diagram over three pages of prose. Amazon’s narrative culture often uses six-pagers for strategy; for most product engineering teams, two to four pages plus links is enough if the summary is honest.

When the RFC touches user-facing behavior, tie goals to outcomes—not output. That discipline matches owning product impact rather than “we shipped the RFC.”

Writing for disagreement, not consensus theater

The point of “Request for Comments” is to surface disagreement early. Invite it explicitly:

• “If you believe Option B is safer for compliance, reply with the scenario we missed.”
• “Red team: what breaks if traffic doubles in November?”

Silent approval is dangerous. Set a comment deadline and a default: “If no blocking concerns by Friday, we proceed with the recommended option and track follow-ups as tickets.”

Avoid language that sounds like a fait accompli unless it truly is (for example, an incident fix with a one-line RFC). Phrases like “we have already started implementation” without prior review erode trust—especially when code review habits depend on people speaking up.

For security-sensitive work, link to your org’s standards and external references such as OWASP ASVS for verification expectations—not to replace your security partner’s review, but to show you know where the bar lives.

Async review mechanics that work

RFCs die in chat threads. Keep the source of truth in one place: a doc in your wiki, a GitHub discussion, or a markdown file in-repo with PR review.

Mechanics that help:

• Stable URL — Same link in Slack, email, and the ticket.
• Revision history — Changelog at the top when you update after feedback.
• Decision record — When resolved, add a “Decision” section: chosen option, date, dissent noted, follow-up tickets.

Time-box review. Two weeks of open-ended comment is often procrastination. One week for initial comments, two days for author revision, then a 30-minute meeting only if blockers remain—many teams skip the meeting entirely.

For cross-team APIs, pair the RFC with typed contracts or OpenAPI sketches. Readers trust proposals that show request/response shapes and error semantics, aligned with designing APIs with types that survive.

Common failure modes

The encyclopedia — Background on every technology since 2004. Move history to an appendix or link.

Missing “do nothing” — Stakeholders cannot weigh cost without a baseline.

Hidden dependencies — “We need platform team bandwidth” buried on page six. Put dependencies and calendar risk in the summary.

No explicit deciders — Comments without a person who can say yes/no/not yet leads to limbo.

RFC after merge — Retroactive docs are archaeology, not governance. If you must ship under incident pressure, publish a short post-incident RFC and schedule the hardening work.

Fabricated precision — “This saves exactly 47% CPU” without measurement belongs in a benchmark appendix, not the executive summary. Qualitative risk statements are fine when honest.

When to skip a full RFC

Not every change deserves a multi-page doc. Use a lighter template for:

• Single-service refactors behind a flag with rollback tested.
• Bug fixes with clear root cause and scoped blast radius.
• Experiments with explicit kill criteria and small user cohorts.

Reserve full RFCs for irreversible or cross-cutting choices: data retention policy, auth model changes, public API versioning, multi-region strategy, or anything that would make shipping AI features users trust harder if you guess wrong.

Closing the loop

After implementation, update the RFC with what happened: surprises, metrics you watched, links to runbooks. Future you—and the next hire—will treat RFCs as institutional memory instead of shelfware.

Strong RFC culture makes senior IC work visible without performative heroics. You are not writing to sound smart; you are writing so the organization can move once—and argue in good faith when the bet was wrong.

Templates and tone for busy readers

Copy a lightweight template into your wiki so authors spend energy on thinking, not formatting. Minimum sections: Summary, Context, Options, Recommendation, Rollout, Open questions, Deciders. Optional appendices for benchmarks, legal notes, or UX mocks.

Write in plain language first; jargon belongs where precision requires it (“we need serializable isolation on this row”) with a one-sentence gloss for adjacent teams. The Plain Language Action and Information Network guidelines are aimed at government communications but help any doc read by mixed audiences—including PM and support leads who will operate the feature.

Tone matters for psychological safety. “We failed to consider X” invites correction; “Anyone who disagrees does not understand distributed systems” shuts it down. Model the review tone you want in code review: curious, specific, respectful of time.

RFCs in regulated or customer-facing contexts

When changes touch privacy, billing, or accessibility, name the reviewer roles in the summary: legal, security, design systems, customer success. Link to your privacy policy diff or WCAG target level if UI changes. External references such as the W3C WCAG overview set expectations without pretending the RFC replaces specialist review.

For customer-visible API or export format changes, include a communication plan: changelog, deprecation window, and support macros. Engineering decisions become product promises the moment docs go public—coordinate with documentation that sells trust rather than surprising GTM teams after deploy.

Measuring whether RFC culture is working

Qualitative signals beat vanity metrics:

• Fewer “how did we decide this?” threads months later.
• Incidents traced to skipped review decrease.
• New hires cite RFCs in onboarding.

If RFCs pile up unread, shrink scope or enforce deadlines. If every change requires a novel, relax thresholds for low-risk work. Culture is a dial, not a religion—adjust it as the team grows from ten to fifty engineers.