<number>_rfc_<snake_case_proposal>.md

# RFC-<number>: <Proposal Title>

Last updated: <YYYY-MM-DD>

## Status

<Draft | In Review | Accepted | Rejected | Withdrawn | Superseded by [RFC-X](link)>

## Review Period

- **Opens**: <YYYY-MM-DD>
- **Closes**: <YYYY-MM-DD>
- **Decision method**: <Consensus | Designated approver(s) | Lazy consensus with timeout>
- **Required reviewers**: <list of teams or individuals who must weigh in>

## Summary

<2-3 sentence executive summary. A busy engineer should understand the proposal from this alone. State what you want to do and the single most important reason why.>

## Motivation

### Problem Statement

<What specific, concrete problem does this solve? Include data, user complaints, incident reports, or developer experience pain points. Quantify the cost of inaction.>

### Why Now

<What has changed that makes this the right time? A new constraint, a growth threshold, a dependency EOL, an upcoming project that will be blocked without this? "Tech debt" is not sufficient motivation -- explain the interest rate.>

### Goals and Non-Goals

**Goals:**
- <Specific, measurable outcome 1>
- <Specific, measurable outcome 2>

**Non-Goals (explicitly out of scope):**
- <Thing that might seem related but is not part of this proposal>
- <Thing that is a future phase, not this RFC>

## Detailed Design

### Architecture Overview

<Describe the proposed architecture. Include a Mermaid diagram for system-level changes.>

```mermaid
graph TD
    A[Component A] --> B[Component B]
    B --> C[New Component]

## When to Write an RFC vs. an ADR

| Signal | RFC | ADR |
|--------|-----|-----|
| Affects multiple teams | Yes | No |
| Introduces new infrastructure component | Yes | No |
| Changes a core abstraction or API contract | Yes | Maybe |
| Requires migration of existing systems | Yes | Maybe |
| Single-team implementation decision | No | Yes |
| Choice between known libraries/tools | No | Yes |
| Needs structured review period with deadlines | Yes | No |

If in doubt, start with an ADR. If reviewers say "this needs more discussion," upgrade to an RFC.

## Review Period Guidelines

| Proposal Scope | Recommended Period | Decision Method |
|---------------|-------------------|-----------------|
| Team-level infrastructure change | 3-5 business days | Team lead approval |
| Cross-team API or data model change | 5-7 business days | Consensus among affected teams |
| Core infrastructure or platform change | 7-10 business days | Architecture review + designated approver |
| Organization-wide process change | 10+ business days | Lazy consensus with explicit timeout |

## Writing Quality Rules

- **Summary**: A VP should be able to read only the Summary and understand what is being proposed. No jargon without definition.
- **Motivation**: Lead with the problem, not the solution. If you cannot articulate the problem without referencing your solution, you do not understand the problem well enough.
- **Detailed Design**: Concrete enough that another engineer could implement it without further design sessions. Use real names, real types, real examples.
- **Drawbacks**: If you cannot name at least 2 drawbacks, you have not thought hard enough. Every design has tradeoffs.
- **Unresolved Questions**: Always include your current leaning. "I don't know" without a leaning shifts the burden entirely to reviewers.

## Anti-patterns

- **RFC for a trivial decision** -- If the change affects only one team and has an obvious answer, use an ADR. RFCs have high coordination cost; reserve them for decisions that genuinely need cross-team input.
- **No Drawbacks section** -- An RFC that claims no drawbacks is either dishonest or insufficiently analyzed. Every proposal has costs. Name them.
- **Mixing multiple proposals** -- One RFC, one proposal. If your RFC has two independent design decisions that could be evaluated separately, split them. Bundling reduces the quality of feedback on each.
- **No Unresolved Questions** -- If you have zero unresolved questions, either you are omniscient or you have not thought carefully enough about edge cases. Include at least 2 genuine questions with your current leaning.
- **Solution-first motivation** -- "We need to adopt X because X is great" is not motivation. Start with the problem, then show why X solves it better than alternatives.
- **Infinite review period** -- RFCs without a deadline never get decided. Always set a close date and decision method. If consensus is not reached by the deadline, the designated approver decides.
- **Design by committee in the doc** -- The RFC author proposes a concrete design. Reviewers critique it. The RFC is not a brainstorming space -- it is a proposal with a position.
- **No migration strategy** -- Proposing a new system without explaining how to get there from the current state is an incomplete proposal. Include the transition plan.