rfc-writer

# RFC Writer Skill

Produce a complete engineering RFC (Request for Comments) for a technical decision or architectural change. An RFC is a structured proposal document — not a persuasion document. Its purpose is to expose a decision to scrutiny, surface trade-offs, document alternatives considered, and create a permanent record of why a choice was made.

A good RFC makes it possible for someone who wasn't in the room to understand years later why the team built something the way they did.

## Required Inputs

Ask for these if not already provided:
- **RFC title and author** — what this RFC is about and who is proposing it
- **Problem being solved** — what is broken, missing, or inadequate today; why action is needed now
- **Proposed solution** — the approach the author is recommending, at least at a high level
- **Context and constraints** — team size, existing architecture, timeline pressures, budget limits, compliance requirements
- **Alternatives considered** — at least 2 alternative approaches the author has thought about
- **Current status** — is this pre-decision (seeking feedback) or post-decision (documenting a made decision)?

## Output Format

---

# RFC [Number]: [Title]

**Author:** [Name] | **Team:** [Team name]
**Created:** [Date] | **Last updated:** [Date]
**Status:** Draft | In Review | Approved | Rejected | Superseded by RFC-[X]
**Ticket:** [JIRA-XXX] | **Slack thread:** [#channel link]
**Review deadline:** [Date — when comments should be submitted by]

---

## Abstract

[2–4 sentences summarising the entire RFC. Should stand alone — someone reading only this should understand what is being proposed, why, and what the main trade-off is. Write this last.]

---

## 1. Problem Statement

[Describe the problem being solved. Focus on the *problem*, not the solution. Be specific and quantified where possible.]

**Current state:**
[Describe how things work today — the existing system, process, or architecture. Include any relevant constraints or limitations.]

**Why this is a problem now:**
[Why is this being addressed now rather than earlier or later? Reference metrics, incidents, product requirements, or scaling thresholds that make this urgent or timely.]

**Example of the problem in practice:**
[A concrete scenario or incident that illustrates the problem. This helps reviewers understand the real-world impact, not just the abstract description.]

```
// Example: current behaviour that illustrates the problem
[code snippet, log output, or sequence description showing the problem]
```

**Impact of not solving this:**
- [Impact 1 — e.g. "New tenant onboarding requires 3 hours of manual configuration per account"]
- [Impact 2 — e.g. "Auth service handles 400 req/s; projected to hit capacity within 8 weeks at current growth"]
- [Impact 3 — e.g. "Current approach is incompatible with the upcoming multi-region requirement"]

---

## 2. Goals and Non-Goals

**Goals:**
- [ ] [Specific, measurable outcome — e.g. "Reduce tenant onboarding time from 3 hours to <5 minutes"]
- [ ] [e.g. "Support 2,000 req/s on the auth service with P99 latency ≤50ms"]
- [ ] [e.g. "Enable multi-region deployment without changes to the application layer"]

**Non-goals:** *(what this RFC explicitly does not address)*
- [e.g. "This RFC does not address authentication for internal service-to-service calls — see RFC-042"]
- [e.g. "Performance improvements to the existing system — this RFC replaces it"]
- [e.g. "Migration of historical data — covered in a follow-on RFC"]

**Success metrics:**
| Metric | Current | Target | Measurement method |
|---|---|---|---|
| [e.g. Onboarding time] | [3 hours] | [<5 minutes] | [Prometheus histogram on onboarding job duration] |
| [e.g. Auth latency P99] | [120ms] | [≤50ms] | [Datadog APM] |
| [e.g. Engineer setup time] | [4 hours] | [<30 minutes] | [Onboarding survey] |

---

## 3. Background and Motivation

[Provide the context a reviewer needs to evaluate the proposal. This is not a repeat of the problem statement — it is the surrounding technical and business context.]

**Existing system overview:**
[Describe the relevant parts of the current architecture. Include an ASCII diagram if the relationships between components help understanding.]

```
[ASCII diagram of current architecture — optional but strongly recommended for architectural RFCs]

  ┌──────────┐     ┌──────────────┐     ┌──────────────┐
  │  Client  │────▶│  [Service A] │────▶│  [Service B] │
  └──────────┘     └──────────────┘     └──────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │  [Database]  │
                   └──────────────┘
```

**Prior work and related decisions:**
- [RFC-XXX: Title — relevant previous decision; link]
- [ADR-XXX: Title — architectural decision record]
- [Any external standards, blog posts, or vendor documentation that informs this proposal]

**Constraints:**
- [e.g. Must remain backward compatible with v1 API clients for 12 months]
- [e.g. Team has no Rust expertise — solution must be in Python or Go]
- [e.g. Must be deployable without a maintenance window]

---

## 4. Proposed Solution

[Describe the proposed approach clearly and specifically. Include enough detail that an engineer could begin implementing from this document, but don't write the code — that is for the PR.]

### 4.1 High-Level Approach

[1–3 paragraphs describing the overall solution. Explain the key idea and why it solves the problem.]

### 4.2 Architecture

```
[ASCII diagram of the proposed architecture — what the system looks like after this RFC is implemented]

  ┌──────────┐     ┌──────────────────┐     ┌──────────────┐
  │  Client  │────▶│  [New Component] │────▶│  [Service B] │
  └──────────┘     └──────────────────┘     └──────────────┘
                           │                       │
                           ▼                       ▼
                   ┌──────────────┐       ┌──────────────┐
                   │  [Store