Engineering

RFC Template for Engineering Teams

An RFC (request for comments) is a short written proposal that asks reviewers to find the problems before the code does. This template adds what most RFC templates leave out: a named approver, a date comments close, and a Decision section, so the review ends instead of trailing off.

Updated 2026-10-27

Copy and adapt

The template

Engineering RFCTemplate

RFC-[number]: [Title]

Status: [Draft / In review / Approved / Rejected / Superseded by RFC-number] Author: [name] Reviewers: [names, and the area each one covers] Approver: [one name] Created: {{date}} Comments close: [YYYY-MM-DD] Decision needed by: [YYYY-MM-DD, and what slips if it is late] Related: [[Project or system name]]

Summary

[If someone reads only this, what should they know? Three sentences: the problem, the proposal, the cost.]

Background

[Why this matters now. Numbers, incidents, prior RFCs. Enough that a reviewer from another team can follow.]

Goals

[Measurable outcome]

Non-goals

[Something a reader might expect this to solve, and it will not]

Proposal

[The approach, at the level a reviewer needs to judge it: components, APIs, data model, diagrams.]

Alternatives considered

[Alternative]

[What it is, and why it was not chosen]

Do nothing

[What the status quo costs, per month or per incident]

Risks and open questions

Security and privacy: [impact, or "none, because ..."]
Performance and cost: [estimate]
Migration and rollback: [how to undo it]
Open question: [question] (@[who can answer])

Rollout plan

[Phase], [date], exit criteria: [what must be true to continue]

Decision

Outcome: [Approved / Approved with conditions / Rejected] on [YYYY-MM-DD] by [approver]
Conditions: [changes reviewers required]
Follow-up: [decision record, tickets, design doc]

4 examples

Examples for different situations

The same structure, filled in for the situations people actually bring to it. Copy the one closest to yours.

1.Approved with conditions: moving cron jobs to a queue

When it fits: Use this when the proposal is technical, the team mostly agrees on the problem, and the review is about whether the chosen solution is the cheapest one that works.

Approved with conditions: moving cron jobs to a queueExample 1

RFC-031: Run background jobs from a Postgres-backed queue instead of cron

Status: Approved Author: Nadia Farouk Reviewers: Grant Liu (database), Esther Mwangi (on-call), Pablo Ortega (billing) Approver: Ingrid Solberg Created: 2026-10-05 Comments close: 2026-10-16 Decision needed by: 2026-10-20, before Q4 planning locks Related: [[Background jobs]]

Summary

Our 23 cron jobs fail silently and cannot be retried. This RFC moves them to a job queue stored in the Postgres database we already run. Cost: about three engineer-weeks, no new infrastructure.

Background

Since June, 7 incidents traced back to cron jobs that failed without anyone noticing, including the invoice run on 2026-09-01 that sent 1,140 invoices a day late. Jobs run on one VM; if it restarts mid-run, the job is lost.

Goals

Every job retries up to 3 times and alerts on final failure.
A dashboard shows last run, duration and status for each job.

Non-goals

Replacing Kafka for event processing.
Sub-second scheduling.

Proposal

Use a queue library that stores jobs in a Postgres table and locks rows with SKIP LOCKED. Workers run in the existing app containers. Schedules move from crontab into code, reviewed like any other change.

Alternatives considered

Redis-based queue

Mature, but adds a stateful service we would have to run and back up. Rejected for operational cost.

Do nothing

Roughly one incident a month and four hours of on-call time each.

Risks and open questions

Performance and cost: extra load on the primary database. Estimate under 2 percent CPU at current volume.
Migration and rollback: migrate one job per day; crontab entries stay commented out for two weeks.
Open question: does the invoice run need exactly-once behavior? (@Pablo)

Rollout plan

Two low-risk jobs, week of 2026-10-26, exit criteria: two weeks with no missed runs.
Remaining jobs, November, invoice run last.

Decision

Outcome: Approved with conditions on 2026-10-19 by Ingrid Solberg
Conditions: load test at 5x current job volume before the invoice run moves (Grant). Invoice job gets an idempotency key (Pablo's answer: yes, exactly-once matters).
Follow-up: decision record DR-018; tickets JOB-201 to JOB-214.

2.In review: public API versioning

When it fits: Use this when the RFC is still open, reviewers disagree, and a fixed external date means the review cannot run forever.

In review: public API versioningExample 2

RFC-044: Version the public API with a date header

Status: In review Author: Callum Reid Reviewers: Mira Patel (developer relations), Sven Larsen (gateway), Adaeze Nwosu (SDKs) Approver: Theo Marchetti Created: 2026-11-09 Comments close: 2026-11-20 Decision needed by: 2026-12-01, because the partner API launches 2027-01-15 and SDKs need six weeks Related: [[Public API]]

Summary

We have shipped three breaking changes in 2026 with no versioning. This RFC proposes that clients send an API-Version header with a date, and each date pins behavior. Unversioned requests get the oldest supported version.

Background

The October change to pagination broke 41 integrations. Support spent 60 hours on it. Partners have asked for a written compatibility promise before signing.

Goals

No breaking change reaches a client that did not opt in.
Support at least 12 months of versions at any time.

Non-goals

Versioning webhooks (separate RFC).

Proposal

Clients send API-Version with a value such as 2027-01-15. The gateway maps the date to a set of response transforms. New breaking changes ship behind a new date.

Alternatives considered

Version in the URL (/v2/)

Easier to see in logs. Mira prefers it for developer experience. Rejected in the draft because every breaking change forces a full new namespace, but this is the main open disagreement.

Do nothing

Each breaking change costs about 60 support hours and partner trust.

Risks and open questions

Performance and cost: response transforms add an estimated 2 ms at p95.
Open question: can the SDKs pin a version automatically? (@Adaeze)
Open question: URL or header. Needs a call from Theo if reviewers do not converge by 11-20.

Rollout plan

Gateway support behind a flag, 2026-12-08.
First dated version 2027-01-15, with the partner launch.

Decision

Outcome: pending. Comments close 2026-11-20; Theo decides by 2026-12-01.

3.Rejected: rewriting the mobile app

When it fits: Use this when the answer is no, and you want the reasons written down so the same proposal does not come back in six months without new evidence.

Rejected: rewriting the mobile appExample 3

RFC-039: Rewrite the iOS and Android apps in a cross-platform framework

Status: Rejected Author: Jonah Whitfield Reviewers: Leila Haddad (iOS), Dmitri Volkov (Android), Kerry Ashford (product) Approver: Samira Bose Created: 2026-09-14 Comments close: 2026-09-25 Decision needed by: 2026-10-01, for 2027 headcount planning Related: [[Mobile apps]]

Summary

Two native codebases mean every feature is built twice. This RFC proposed rewriting both apps in one cross-platform framework over three quarters, with four engineers.

Background

In 2026 the Android app shipped features an average of 5 weeks after iOS. Android has 2 engineers, iOS has 4.

Goals

Feature parity on the same release date.

Non-goals

Changing the design system.

Proposal

Freeze native feature work for one quarter, rebuild the shared screens, ship screen by screen inside the existing apps.

Alternatives considered

Hire two Android engineers

Addresses the gap directly. Not chosen in the draft because hiring takes a quarter.

Risks and open questions

Migration and rollback: a three-quarter rewrite with a feature freeze in the first one.

Decision

Outcome: Rejected on 2026-09-30 by Samira Bose
Reasons: the parity gap is a staffing gap, not an architecture gap; a quarter-long feature freeze is not affordable in the year of the enterprise launch; the rewrite estimate had no prototype behind it.
Instead: hire two Android engineers in Q4 (approved). Revisit only with a two-screen prototype and measured build times.

4.Approved for a trial: a process change, not a code change

When it fits: Use this when the RFC changes how people work rather than what the system does, and the decision is a time-boxed trial with criteria for keeping it.

Approved for a trial: a process change, not a code changeExample 4

RFC-047: Split on-call between Lisbon and Austin (follow the sun)

Status: Approved Author: Beatriz Carvalho Reviewers: Wyatt Bell (Austin lead), Fatima Zahra (SRE), Olu Bankole (people team) Approver: Rachel Stone Created: 2026-11-02 Comments close: 2026-11-13 Decision needed by: 2026-11-20, so the January rota can be published Related: [[On-call rotation]]

Summary

Each engineer is on call for a full week, nights included. This RFC splits each day into two 12-hour shifts, Lisbon days and Austin days, so nobody is paged at night in their own time zone.

Background

Between July and October there were 38 night pages; 3 engineers asked to leave the rota. Austin and Lisbon each have 6 engineers on the rota.

Goals

Night pages in local time fall by at least 80 percent.
Handoff takes under 10 minutes and loses nothing.

Non-goals

Changing on-call pay. The people team is handling that separately.

Proposal

Shifts change at 08:00 and 20:00 Lisbon time. Each handoff is a written note in the on-call channel: open incidents, anything degraded, anything deployed in the last four hours.

Alternatives considered

Keep weekly shifts, add a night allowance

Pays people for the problem instead of removing it.

Risks and open questions

Handoffs: incidents that span 20:00 need a clear owner. Rule: the person who declared it keeps it until mitigated.
Open question: what happens during US holidays? (@Wyatt)

Rollout plan

Trial January to March 2027. Exit criteria: night pages down 80 percent, no incident where handoff added more than 15 minutes.

Decision

Outcome: Approved as a trial on 2026-11-18 by Rachel Stone
Conditions: handoff note template agreed before 2027-01-05 (Fatima). US holidays covered by Lisbon, with comp days (Wyatt's answer).
Follow-up: review on 2027-04-07 against the exit criteria.

What an RFC is for

An engineering RFC is a proposal written before the work starts, shared with the people who will live with the result, and closed with a decision. Most RFC templates agree on the core: summary, background, goals and non-goals, proposal, alternatives, risks. They mostly stop there. What they leave open is how the review ends. A proposal with no approver and no deadline collects comments for three weeks and then either stalls or gets built anyway, with the objections still unanswered.

That is why the header of this template carries a single approver, a date comments close, and a date the decision is needed by, and why the last section is the decision itself.

RFC, design doc or decision record

These three documents get mixed up because they overlap.

RFC. Asks for a decision on a proposal. Written before the work, reviewed by the people affected.
Design doc. Explains how the approved thing will be built, in more detail than reviewers need. See how to write a software design document.
Architecture decision record. A short, permanent record of a decision and its context, often one per RFC that gets approved. See these architecture decision record examples.

Small teams can merge all three into one RFC with a good Decision section. Larger teams write the RFC, then file a short decision record that links back to it.

How to run the review

Circulate with a deadline. One to two weeks of comments. Name the reviewers and the area you need each to check, so security does not review the database schema.
Answer comments in the document. Resolve each one with a change, a non-goal, or a reason it was not taken. Unresolved comments are the agenda for a review meeting, if you need one.
The approver decides on the date. Approve, approve with conditions, or reject. "Needs more discussion" is not an outcome; if it truly needs more, set a new date.
Update the status and link the follow-ups. Tickets, the decision record, the design doc. Then the RFC is done.

Writing a proposal people can review

Reviewers can only disagree usefully with something specific. Put numbers in the background: incidents, hours, error rates. Write goals that can be checked later. Give each alternative a fair paragraph and a reason it lost, because a reviewer who suspects you did not consider their preferred option will spend the review arguing for it. And include doing nothing, with its cost.

Common mistakes

Writing the RFC after the code. Then it is documentation, and reviewers know their comments will not change anything.
No non-goals. Every reviewer brings a neighboring problem, and the review sprawls.
Hiding the disagreement. If a reviewer disagrees, say so in the alternatives and let the approver decide with it in view.
Deleting rejected RFCs. The reasons for a "no" are worth as much as the reasons for a "yes".

When to use a different template

If the question is what to build rather than how, start with a PRD template or a project brief. If the decision is small and you only need to record it, a decision log entry is enough. And if you need buy-in from people who will not read five pages, a one-pager is the format they will finish.

Customization tips

Name one approver
Reviewers comment; one person decides. Without a named approver, an RFC collects comments until everyone loses interest, and the work starts anyway with the disagreements unresolved.
Put the deadline in the header
"Decision needed by" with the reason (headcount planning, a partner launch) tells reviewers how much time they have. A comment window of one to two weeks is enough for most RFCs.
Always include doing nothing
The status quo is an alternative with a cost. Putting a number on it (support hours, incidents per month) is often the most persuasive line in the document.
Write non-goals before the proposal
Non-goals cut the review in half. Most off-topic comments are someone expecting the RFC to solve a neighboring problem; a non-goal answers them in advance.
Short RFCs for small changes
For a change that affects one team, Summary, Proposal, Alternatives and Decision are enough. Keep the full template for changes that cross teams or are hard to undo.

In the app

How to do this in Scribelet

Open Desk Settings, then Templates, tap Add Template, paste the template above, choose the General category and set #rfc as a default tag. Keep {{date}} so the created date fills itself in.
Link the system with [[Public API]] and earlier RFCs with [[RFC-031]]. The system note's backlinks then list every RFC that touched it, approved or rejected, which is the history new team members ask for.
Write the comment deadline as a task: - [ ] Close comments on RFC-044 @due(2026-11-20). It shows up in the Tasks view, and @remind(2026-11-20 09:00) sends you a push reminder on the day.
Ask the AI chat "have we proposed rewriting the mobile app before, and why was it rejected?" It answers from your RFCs with citations, so rejected ideas come back with their reasons attached.
With the GitHub connector, opt an approved RFC in from its Settings. Background verification (Pro) checks the claims in it against the repository and proposes a diff when the implementation has moved on.

Templates, template variables and AI generation are documented in Note templates.

Frequently asked questions

What is an RFC in software engineering?

A request for comments is a written proposal for a significant technical or process change, shared before the work starts so reviewers can find problems while they are cheap to fix. It ends in a decision: approved, approved with conditions, or rejected. The term comes from the IETF's internet standards, but engineering teams use it for internal design proposals, which is what this template is for.

What is the difference between an RFC and a design doc?

An RFC asks for a decision on a proposal and is usually short. A design doc describes how an approved thing will be built, in more detail. Many teams use one document for both; others write the RFC first and a software design document after approval.

How long should an RFC be?

Two to five pages for most proposals. If the background runs over a page, link to it instead. If reviewers cannot find the proposal in the first screen, the summary is not doing its job.

Who approves an RFC?

One named person, usually the tech lead or engineering manager who owns the affected system, or an architecture group for cross-team changes. Reviewers are chosen per area (security, database, the teams affected) and their job is to raise issues, not to vote.

Should rejected RFCs be kept?

Yes. A rejected RFC with its reasons is the cheapest way to stop the same idea being proposed again without new evidence, and the reasons tell the next author what evidence would change the answer.

Is this the same as an IETF RFC or an ITIL request for change?

No. IETF RFCs are published internet standards with their own format. An ITIL RFC is a "request for change" ticket in IT service management. This template is for engineering teams proposing a design or process change internally.

Proposals that end in a decision, and decisions you can find later

Write RFCs in Scribelet from this template, link each one to the system it changes, and track comment deadlines as tasks. Next year, ask your notes why the mobile rewrite was rejected and get the answer with a citation. Encrypted, free to start.

Write your first RFC

or get the app

Download on theApp Store

Free plan, no credit card. See pricing

Guide

Note Taking App for Developers: Markdown, MCP and Notes Checked Against Your Code

Developer notes fail in a specific way: they are right on the day they are written and quietly wrong six months later. This page says which tool fits which developer, what belongs in the repo instead, and a setup where notes are Markdown, your coding agent can read and write them over MCP, and runbooks get checked against the actual code.

Work

Decision Log Template

A decision log is a running record of what was decided, why, by whom, and what you expected to happen. This template adds the two fields most logs leave out: who disagreed, and a date to check whether the decision worked. Copy it for a team, or use the decision journal example for your own choices.

Work

One Pager Template

A one-pager exists to get one decision from a reader who will give it two minutes. This template puts the ask at the top, gives every section a word budget so the whole thing fits on a page, and keeps the detail in a linked appendix. Copy it, or start from the filled-in one-pager closest to yours.

Product

PRD Template (Product Requirements Document)

A PRD (product requirements document) says what problem a release solves, for whom, how you will know it worked, and what it deliberately will not do. This template keeps it short enough to be read, and adds what most PRD templates leave out: a status, a decision log, and open questions with owners and dates.

Projects

Project Brief Template

A project brief fits on one page and gets a yes: what problem this solves, what will be true when it is done, what is in and out, what it costs, and who approves it. Copy the template, or start from the example closest to your project.

Article

Software design document

From the Scribelet blog