A Request for Comments (RFC) is a formal written document that proposes a solution to a problem and seeks feedback on that proposal. Unlike a PRD which focuses on the problem, an RFC focuses on the solution.

Key principle: An RFC facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but a collaborative practice to shape an idea and find serious flaws early.

When to Use an RFC

Use an RFC when:

A change will affect many stakeholders
Proposing a significant technical solution
Seeking thoughtful feedback across distributed teams
Making important cross-functional decisions
The implementation approach needs validation

Skip an RFC when:

The change is trivial or well-understood
You're the sole decider without needing input
A quick discussion would suffice

RFC vs PRD

Document	Focus	When to Write
PRD	The problem and requirements	Before solution design
RFC	The solution and implementation	After problem is understood

A PRD answers: "What problem are we solving and why?" An RFC answers: "How will we solve it?"

RFC Template Structure (HashiCorp Format)

1. Metadata

# [RFC] Title: Brief Description of Proposal

| Field | Value |
|-------|-------|
| **Created** | [Date] |
| **Current Version** | [Version] |
| **Target Version** | [Version] |
| **PRD** | [Link if applicable] |
| **Status** | WIP / In-Review / Approved / Obsolete |
| **Owner** | [Name] |
| **Contributors** | [Names] |

Status Labels

Status	Meaning
WIP	Still drafting; not ready for review
In-Review	Ready for feedback from stakeholders
Approved	Decision finalized, ready for implementation
Implemented	Proposal executed
Obsolete	Superseded by another RFC
Abandoned	Decision made not to proceed

2. Overview

Purpose: Provide a brief executive summary (1-2 paragraphs).

Important: Anyone opening the document should form a clear understanding of the RFC's intent from reading this section alone.

Include:

What this RFC proposes (high-level)
The goal or outcome expected
NOT the detailed "why", "why now", or "how"

## Overview

This RFC proposes [solution] to address [problem summary]. The expected
outcome is [benefit/goal]. This change will affect [scope/systems].

3. Background

Purpose: Provide full context so any reader can understand why this RFC is necessary.

Key test: If you can't show a random engineer the background section and have them acquire nearly full context on the necessity for the RFC, the background is not complete enough.

Include:

Current state of the system
Why this change is needed now
Links to prior RFCs, discussions, PRDs
Historical context and previous attempts
Technical constraints

## Background

### Current State
[How things work today. What exists. The status quo.]

### Problem Context
[Why the current state is insufficient. Link to PRD if available.]

### Prior Work
[Previous RFCs, discussions, or attempts. What was learned.]

### Constraints
[Technical, organizational, or time constraints affecting the solution.]

**Related Documents**:
- PRD: [link]
- Previous RFC: [link]
- Discussion: [link]

4. Proposal / Goal

Purpose: Given the background, propose the solution.

This section provides an overview of the "how" without diving into implementation details (those come in the next section).

## Proposal

### Goal
[What we're trying to achieve with this solution]

### Proposed Solution
[Overview of the approach. High-level description of how it works.]

### Key Design Decisions
1. **[Decision 1]**: [Rationale]
2. **[Decision 2]**: [Rationale]
3. **[Decision 3]**: [Rationale]

### Scope
- **In Scope**: [What this RFC covers]
- **Out of Scope**: [What this RFC does NOT cover]

5. Implementation

Purpose: Detail how the implementation will work.

Include:

API changes (internal and external)
Package/module changes
Data model changes
Subsystems affected
Surface area of changes

## Implementation

### Architecture Overview
[High-level architecture diagram or description]

### Component Changes

#### [Component 1]
**Current**: [How it works now]
**Proposed**: [How it will work]
**Changes Required**:
- [Change 1]
- [Change 2]

#### [Component 2]
[Same structure]

### API Changes

#### New Endpoints/Methods

POST /api/v1/widgets Request: { "name": string, "config": object } Response: { "id": string, "status": string }


#### Modified Endpoints/Methods
[Existing API changes]

#### Deprecated Endpoints/Methods
[What will be deprecated and timeline]

### Data Model Changes
[Database schema changes, new tables, migrations]

### Dependencies
[External dependencies, services, libraries]

6. UI/UX (If Applicable)

Purpose: Document user-impacting changes.

Include any changes to:

External API surface
Configuration formats
CLI output
User interfaces
Error messages

## UI/UX

### User-Facing Changes

#### CLI Changes

Before

$ tool config --format json

After

$ tool config --format json --validate


#### Configuration Changes
```yaml
# New configuration option
widgets:
  enabled: true
  max_count: 100

Error Message Changes

[New or modified error messages users will see]

Migration Guide

[How users migrate from old to new behavior]

Documentation Updates Required

[Doc page 1]
[Doc page 2]


### 7. Rollout Plan

**Purpose**: Describe how this will be deployed and validated.

```markdown
## Rollout Plan

### Phases

#### Phase 1: [Description]
- **Timeline**: [Dates]
- **Scope**: [What's included]
- **Success Criteria**: [How we know it worked]
- **Rollback Plan**: [How to revert if needed]

#### Phase 2: [Description]
[Same structure]

### Feature Flags
[Any feature flags used for gradual rollout]

### Monitoring
[Metrics and alerts to watch during rollout]

8. Testing Strategy

Purpose: Describe how the solution will be validated.

## Testing Strategy

### Unit Tests
[Key unit test scenarios]

### Integration Tests
[Integration test approach]

### Performance Tests
[Load testing, benchmarks]

### Manual Testing
[Manual validation steps]

### Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

9. Security Considerations

Purpose: Address security implications.

## Security Considerations

### Threat Model
[What threats does this introduce or mitigate?]

### Authentication/Authorization
[Changes to auth model]

### Data Handling
[Sensitive data considerations]

### Audit/Compliance
[Audit trail, compliance requirements]

10. Abandoned Ideas

Purpose: Document ideas that were considered but rejected.

Important: Don't delete abandoned ideas from the document. Organize them with explanations of why they were abandoned. This preserves the reasoning for future readers.

## Abandoned Ideas

### [Idea 1 Title]

**Description**: [What was proposed]

**Why Abandoned**: [Reason it was rejected]

**Discussion**: [Link to relevant discussion if any]

### [Idea 2 Title]
[Same structure]

11. Open Questions

Purpose: List unresolved questions that need input.

## Open Questions

1. **[Question]**
   - Context: [Why this matters]
   - Options: [Possible answers]
   - Owner: [Who will decide]

2. **[Question]**
   [Same structure]

12. References

## References

- [Related RFC 1](link)
- [External documentation](link)
- [Research/papers](link)

RFC Best Practices

Writing

Background is critical: If a newcomer can't understand why this RFC exists from the background section alone, it's incomplete
Link liberally: Reference prior RFCs, discussions, PRDs, and documentation
Be specific: Include API signatures, data structures, configuration examples
Show your work: Document abandoned ideas so readers understand the decision process

Process

Share early: Get feedback while still in WIP status
Invite the right reviewers: Identify stakeholders who will be affected
Iterate openly: Update the RFC based on feedback
Don't rush approval: Consensus takes time in async environments

Common Mistakes

Skipping background: Assuming readers know the context
Solution without problem: Proposing a fix without establishing what's broken
Missing abandoned ideas: Deleting rejected approaches instead of documenting them
Vague implementation: "We'll figure it out" instead of concrete details
No rollback plan: Assuming everything will work perfectly

RFC Review Checklist

Before marking an RFC as ready for review:

RFC Types

Full RFC

Use for:

Major architectural changes
New features affecting multiple teams
Changes with significant risk or complexity

Mini RFC

Use for:

Minor features or enhancements
Changes limited in scope
Maintenance tasks

Mini RFC Sections:

Problem Statement (concise)
Proposed Solution (high-level)
Implementation Details (brief)
Success Metrics
Questions/Concerns

Additional Resources

For detailed template: See references/hashicorp-template.md
For best practices from industry: See references/best-practices.md