| name | rfc |
| description | Comprehensive RFC (Request for Comments) writing skill based on HashiCorp's template. Use this skill when proposing technical solutions, seeking feedback on designs, or documenting engineering decisions. Covers overview, background, proposal, implementation, UI/UX considerations, and abandoned ideas. |
RFC (Request for Comments) Writing Skill
This skill provides guidance for creating effective RFCs that propose solutions and drive consensus through collaborative feedback.
What is an RFC?
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
### 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
References
