| name | writing-rfc |
| description | Write an RFC or design doc — summary-first, with goals/non-goals, real alternatives, drawbacks, and open questions. Use when proposing a technical change for review, writing a design doc, or documenting a system or feature proposal before building it. |
RFC / Design Doc Writing
An RFC argues a proposal and its alternatives before you build. It is for a change
worth thinking through in the open. (For recording a decision already made, use
writing-adr; for general technical writing principles, writing-technical.)
The rule that governs everything
Lead with the answer (BLUF). The Summary states the proposal in full; a reader who
stops there still knows what and why. Don't make reviewers excavate the point.
Honesty is the structure, not a footnote. The Alternatives, Drawbacks, and Open
Questions sections are where the document earns trust. A proposal with no stated
downsides reads as unconsidered, not as strong. Steelman what you rejected.
Skeleton
- Title —
RFC-NNN: <imperative summary>.
- Status — Draft / Under review / Accepted / Rejected · date · author.
- Summary — the proposal in 3–5 sentences. Self-contained.
- Motivation / Problem — concrete, with the symptom or metric that forced it.
- Goals & Non-goals — bound the scope explicitly. Non-goals prevent scope creep
and review noise; they are not optional.
- Proposed design — the mechanism in plain language. Define jargon; prefer a
small worked example or diagram. Quantify (latency, cost, throughput).
- Alternatives considered — real options, each with an honest why-not. Not
strawmen. The reader should trust you argued against yourself.
- Drawbacks / Risks — what this costs, what could go wrong, blast radius.
- Open questions — what you don't know yet, and what evidence would resolve each.
- Rollout / migration — steps, fallbacks, and how you'll know it worked.
Filling it well
- Every claim attached to a number or precedent — not "faster," but "4× write spike
at launch, drains in minutes."
- Headers are the skeleton above; keep them so reviewers can navigate by convention.
- A non-goal that says what you're explicitly not solving is worth a paragraph of
prevented debate.
- For open questions, name the experiment or data that would settle each one. End with
the question that decides whether to ship at all.
- Rollout should let a reader reverse the change: fallback, rollback, verification.
Checklist
