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:

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 A]   │       │  [Store B]   │
                   └──────────────┘       └──────────────┘

4.3 Detailed Design

[Break the solution into its key components or decisions. For each, explain what it does and why it was designed this way.]

Component / Decision 1: [Name]

[Description of this component — what it does, how it works, why this approach was chosen.]

// Example interface, API contract, or pseudocode (not implementation code)
[Relevant schema, API definition, data flow, or pseudocode]

Component / Decision 2: [Name]

[Description]

Component / Decision 3: [Name]

[Description]

4.4 API Changes

Complete this section if the RFC introduces or modifies any API endpoints, events, or interfaces.

New endpoints / events:

[HTTP method + path or event name]
Request: { ... }
Response: { ... }

Modified endpoints:

• [endpoint]: [what changes and why; backward compatibility note]

Deprecated endpoints:

• [endpoint]: deprecated in favour of [new endpoint] — removal timeline: [date/version]

4.5 Data Model Changes

Complete this section if any database schema or data structure changes are required.

[Describe schema changes at a high level. Reference the database-migration-plan skill for detailed migration steps.]

-- Key schema changes (abbreviated — full migration in [link])
[DDL statements for key additions/changes]

5. Alternatives Considered

Every alternative must include an explicit reason why it was rejected. "We went with the proposed solution" is not a reason.

Alternative 1: [Name]

Description: [What this alternative would involve.]

Pros:

• [Pro 1]
• [Pro 2]

Cons:

• [Con 1]
• [Con 2]

Why rejected: [Specific reason — e.g. "Requires 3× the infrastructure cost", "Incompatible with multi-region requirement", "Team has no expertise in this technology and the ramp-up would miss the Q3 deadline"]

Alternative 2: [Name]

Description: [What this al