RFC template for engineering teams (+ design doc)

An RFC (request for comments) is a written proposal for a significant technical change, shared before anyone builds it. A design doc is the same idea under a different name. This page has a copy-paste RFC template, notes for using it in Confluence, a review process, and the step most teams skip: turning the outcome into a decision record that still means something after the RFC goes stale.

The RFC template (Markdown)

Copy this into docs/rfcs/0007-short-title.md or a new Confluence page. Delete sections that don't apply; keep Problem, Proposal, Alternatives, and Decision.

# RFC-0007: [Short title, e.g. "Move background jobs to a dedicated queue"]

| Field          | Value                                        |
| -------------- | -------------------------------------------- |
| Author(s)      | @name                                        |
| Decider        | @one-person who makes the final call         |
| Reviewers      | @names (required), @names (optional)         |
| Status         | Draft / In review / Accepted / Rejected / Withdrawn |
| Review closes  | YYYY-MM-DD                                   |
| Related        | links to tickets, ADRs, prior RFCs           |

## Summary
Two or three sentences a busy reader can stop after.

## Problem
What is wrong or missing today, and who it affects. Include evidence:
incidents, metrics, support tickets, user feedback.

## Goals
- What this change must achieve

## Non-goals
- What this change deliberately does not try to do

## Proposal
The design. Diagrams, data model changes, API changes, sequence of calls.
Enough detail that a reviewer can find the flaw if there is one.

## Alternatives considered
- Alternative A: how it would work, why we're not choosing it
- Alternative B: ...
- Do nothing: what happens if we don't do this

## Risks and trade-offs
What could go wrong, what gets harder, what we're committing to.

## Security, privacy and compliance
Data touched, new access paths, anything needing review.

## Rollout and rollback
Migration plan, feature flags, how we undo it if it goes wrong.

## Testing and observability
How we'll know it works: tests, metrics, alerts, dashboards.

## Open questions
- Question, and who can answer it

## Decision
Filled in by the decider when review closes:
Accepted / Rejected, date, one-paragraph rationale, link to the ADR or
decision log entry that records it.

Using the RFC template in Confluence

• Header table. Put the field table inside a Page Properties macro and label the page rfc. A Page Properties Report on a parent "RFCs" page then lists every RFC with its status, decider and review deadline. It's the same pattern as the Confluence decision log template.
• Save it as a space template so every new RFC starts with the right sections and label.
• Use inline comments for review, and ask reviewers to resolve them or turn them into Open questions. A wall of page-bottom comments is hard to close out.
• Mentions for reviewers. Put required reviewers as @mentions in the header so they're notified when the page is published.

Repo-based RFCs (a Markdown file in a pull request) have one advantage: review threads, approvals and the final merge happen in one place and are versioned. Confluence wins when the readers aren't all engineers.

A review process that ends in a decision

1. Draft. The author writes the RFC and gets one informal read from a peer before circulating.
2. Open review with a deadline. Status moves to In review. The header names the decider and the date review closes.
3. Discuss in writing. Comments on the doc. If a meeting is needed, its outcome is written back into the RFC.
4. Decide. On the deadline, the decider accepts, rejects, or asks for a revision with a new date. "No decision" is not an outcome.
5. Record. The decision is written up as an ADR or decision log entry, linked from the RFC's Decision section.
6. Freeze. The RFC is no longer edited. Later changes go into a new RFC or a superseding ADR.

The single most useful rule here is the named decider. Many RFC processes stall because review has no owner; frameworks like DACI exist mainly to fix that.

RFC → decision → ADR or decision log

An RFC is a conversation. Once the work ships, nobody re-reads a 6-page proposal to find out what was agreed, and parts of the proposal will have changed during review anyway. So the outcome needs its own short, durable record:

Artifact	Purpose	Length	Lifespan
RFC / design doc	Explore and debate a proposal	Several pages	Stale after the work ships
ADR	Record an architecture decision and its consequences	1–2 pages	Authoritative until superseded
Decision log entry	Record any decision (product, pricing, process, architecture)	Half a page	Authoritative until superseded

The ADR or log entry should link back to the RFC for anyone who wants the full debate, and state the decision in a form someone could follow without reading the RFC. For example, RFC-0007 might produce "ADR-0012: Move background jobs to a managed queue service", with Context summarizing the RFC's Problem section and Consequences carrying over the accepted risks.

Common RFC mistakes

• No non-goals. Reviewers argue about scope instead of design.
• Alternatives as strawmen. If the alternatives section doesn't contain one option you seriously considered, reviewers can't trust the proposal.
• No deadline, no decider. The RFC sits in review until it's irrelevant.
• Decisions that only live in comment threads. "OK, we'll skip the migration for v1" in a comment is a decision. If it isn't copied into the Decision section or an ADR, it's effectively lost.

Where Lockstep fits

That last mistake is the one templates can't fix: decisions made in review threads, Slack and follow-up meetings that never get written back. Lockstep watches Slack, Jira and Confluence (including RFC pages and their comments), drafts decision entries, and sends each to its owner for one-click approval. Approved decisions then brief engineers and AI coding agents via MCP, and a PR check flags changes that may conflict. It's early, open source, and meant to sit alongside your RFC process, not replace it. If you also keep a separate decision log, see why engineering decision logs starve.