Requests for Comment (RFCs)

A Request for Change (RFC) is a structured document used to propose, discuss, and document significant technical or organizational decisions. Think of it as a formal way to think through changes before implementing them, ensuring everyone understands the problem, the proposed solution, and the implications.

What are RFCs?

RFCs help you:

Propose Changes: Present ideas for significant changes or features
Document Thinking: Capture the reasoning behind decisions
Enable Collaboration: Get feedback from team members before committing
Create Records: Maintain a history of why decisions were made
Reduce Risk: Identify problems and alternatives before implementation
Align Teams: Ensure everyone understands what's being built and why

RFC Properties

Each RFC has:

Basic Information

RFC Number: Auto-generated identifier (e.g., "RFC-2024-001")
Title: Clear, descriptive name for the change being proposed
Summary: Brief overview of what the RFC proposes
Author: The person who created the RFC
Status: Current state of the RFC (open, closed, or converted to ADR)
Project: Which project this RFC belongs to (required)
Statement of Work: Optional link to a specific SOW
Organization: Which organization owns this RFC

Status Lifecycle

Open:

RFC is being drafted or discussed
Can be edited and updated
Accepting feedback and comments
Not yet decided

Closed:

Decision has been made (accepted or rejected)
No longer accepting changes
Locked for historical reference
May have moved to implementation

ADR Created:

Decision was accepted
Converted to an Architecture Decision Record
Documented in formal architecture docs
Represents a binding decision

Collaborators

Owner: The RFC author (automatically added)
Collaborators: Team members contributing to the RFC
Each collaborator can view and edit while RFC is open

Created/Updated

Created At: When the RFC was first written
Updated At: Last time any changes were made
Close Date: When the RFC was closed (if applicable)

RFC Structure

RFCs are organized into sections that guide you through documenting your proposal:

Standard RFC Sections

Understanding the Problem

Summary:

High-level overview of what's being proposed
What problem are you solving?
Why is this important?

Problem Statement:

Detailed explanation of the current problem
Who is affected?
What's the impact of not solving this?

Background:

Context and history
What led to this problem?
What have we tried before?

Motivation:

Why solve this now?
What are the benefits?
What happens if we don't address this?

Proposing the Solution

Solution Overview:

High-level description of the proposed solution
Key concepts and approach
What will change?

Technical Details:

Specific implementation details
Technologies and tools involved
Architecture and design decisions
Code examples or diagrams

UX/UI Considerations:

User experience implications
Interface changes
Usability concerns
Design mockups or wireframes

Alternatives Considered:

Other approaches you evaluated
Why were they rejected?
Trade-offs between options

Analyzing Impact

Technical Impact:

How does this affect existing systems?
Performance implications
Scalability considerations
Technical debt created or resolved

Organizational Impact:

Team structure changes
Training needs
Process modifications
Resource requirements

Security Impact:

Security implications
New vulnerabilities introduced
Security improvements
Compliance considerations

Operational Impact:

Deployment complexity
Monitoring and maintenance
Support requirements
Incident response changes

Planning Implementation

Implementation Plan:

Step-by-step approach
Phases or milestones
Testing strategy
Rollout plan

Timeline:

Estimated duration
Key dates and deadlines
Dependencies on other work

Dependencies:

What must be done first?
External dependencies
Team dependencies
Resource constraints

Risks and Mitigations:

What could go wrong?
How likely are these risks?
How can we mitigate them?

Reaching Conclusion

Open Questions:

Unresolved issues
Areas needing more research
Items for future discussion

Decision:

Final decision made (accept, reject, defer)
Who made the decision?
When was it decided?

Decision Rationale:

Why this decision was made
Key factors that influenced it
Trade-offs accepted

Creating an RFC

When to Write an RFC

Create an RFC when you need to:

Propose a significant architectural change
Introduce a new technology or tool
Change a core system or process
Make a decision with long-term implications
Resolve a complex technical problem
Coordinate a large, multi-team effort

When NOT to Write an RFC

Skip the RFC for:

Small bug fixes
Minor refactoring
Routine maintenance
Well-established patterns
Individual task decisions
Urgent production issues (address first, document later)

Starting Your RFC

Choose Your Project
- Select the project this RFC relates to
- Optionally link to a specific Statement of Work
Write a Clear Title
- Be specific and descriptive
- Example: "Migrate user authentication to OAuth 2.0"
- Not: "Auth changes"
Draft a Summary
- 2-3 sentences explaining the proposal
- What, why, and high-level how
Add Collaborators
- Invite team members who should contribute
- Include stakeholders who need visibility

Building Your RFC

Fill in the sections:

Start with problem statement and background
Explain your proposed solution
Document alternatives you considered
Analyze the various impacts
Create an implementation plan
List open questions and risks
Leave decision sections for later

Tips:

Write clearly and concisely
Use diagrams and examples
Link to relevant resources
Update as you learn more
Iterate based on feedback

The RFC Workflow

1. Draft Phase (Status: Open)

Activities:

Write the initial RFC
Fill in key sections
Add diagrams or examples
Invite collaborators

Who's Involved: RFC author, early collaborators

2. Review and Discussion (Status: Open)

Activities:

Share with team for feedback
Discuss in meetings or comments
Refine the proposal
Address questions and concerns
Update sections based on feedback

Who's Involved: Collaborators, stakeholders, technical reviewers

3. Revision (Status: Open)

Activities:

Incorporate feedback
Update technical details
Refine implementation plan
Resolve open questions
Consider alternatives raised

Who's Involved: RFC author with input from team

4. Decision (Status: Changes to Closed or ADR Created)

Outcomes:

Accepted:

Change status to "ADR Created"
Document the decision and rationale
Convert to Architecture Decision Record
Move to implementation

Rejected:

Change status to "Closed"
Document why it was rejected
Preserve for future reference
May revisit later

Deferred:

Change status to "Closed"
Document reasons for deferral
Note conditions for reconsidering
Preserve the research

5. After Closure

Once closed, the RFC:

Becomes read-only
Serves as historical record
Can be referenced in code or docs
Provides context for future decisions

Working with RFCs

Viewing RFCs

You can see RFCs in different ways:

All RFCs: Every RFC in your organization
Project RFCs: All RFCs for a specific project
By Status: Filter to open, closed, or ADR-created
Search: Find RFCs by title, summary, or content

Editing RFCs

While Open:

Edit any section
Add or remove collaborators
Update implementation details
Refine based on feedback

When Closed:

Cannot edit content
Can only update status
Preserved as historical record

Collaborating on RFCs

As a Collaborator:

Read and understand the proposal
Provide constructive feedback
Suggest alternatives
Ask clarifying questions
Help refine the solution

As the Author:

Incorporate feedback thoughtfully
Respond to questions
Update the RFC as it evolves
Drive toward a decision
Document the final outcome

RFC Best Practices

Writing Effective RFCs

Do:

Start with the problem, not the solution
Be specific and concrete
Consider multiple alternatives
Analyze all types of impact
Identify risks honestly
Update as you learn
Keep it concise but thorough

Don't:

Jump straight to implementation details
Ignore alternatives
Downplay risks or negative impacts
Write once and never update
Make it too long (aim for clarity over length)
Skip the rationale

Problem Statement Tips

Good Problem Statements:

"Users currently cannot reset their passwords without
contacting support, resulting in 50+ support tickets
per week and frustrated users unable to access their
accounts quickly."

Poor Problem Statements:

"Password reset doesn't work well."

What makes it good:

Specific impact (50+ tickets/week)
Identifies who's affected (users, support team)
Explains the consequence (frustration, slow access)
Measurable and clear

Solution Description Tips

Good Solution Descriptions:

"Implement a self-service password reset flow that
sends a secure, time-limited reset link to the user's
email. The link expires after 1 hour and can only be
used once. Users can initiate this from the login page
without support intervention."

Poor Solution Descriptions:

"Add password reset functionality."

What makes it good:

Specific approach (email with time-limited link)
Security considerations (expires, single-use)
User experience (from login page, self-service)
Clear boundaries (no support needed)

Decision-Making Guidelines

Accept when:

Problem is well-understood
Solution addresses the problem
Impacts are acceptable
Team has consensus
Implementation is feasible

Reject when:

Problem isn't significant enough
Solution has major drawbacks
Better alternatives exist
Timing is wrong
Resources aren't available

Defer when:

More research is needed
Dependencies aren't ready
Priorities have shifted
Better to wait for X to complete

Common RFC Patterns

Technical Architecture RFCs

Focus on:

System design and architecture
Technology choices
Integration patterns
Data models
API design

Key Sections:

Technical Details
Technical Impact
Implementation Plan
Alternatives Considered

Process Change RFCs

Focus on:

Team workflows
Development processes
Deployment procedures
Communication patterns

Key Sections:

Organizational Impact
Implementation Plan
Timeline
Training needs

Infrastructure RFCs

Focus on:

Hosting and deployment
Scaling and performance
Monitoring and alerting
Security and compliance

Key Sections:

Technical Details
Operational Impact
Security Impact
Costs and resource implications

Linking RFCs to Work

Connect to Projects

Every RFC must belong to a project:

Shows which client or initiative it relates to
Groups related RFCs together
Provides organizational context

Optional SOW Links

Link an RFC to a specific Statement of Work when:

The RFC proposes changes for a specific deliverable
Implementation will be part of a particular SOW
You want to track RFC as part of that work

Note: The SOW must belong to the same project as the RFC.

From RFC to Implementation

When an RFC is accepted:

Convert to ADR (Architecture Decision Record)
- Document the binding decision
- Add to architecture documentation
- Status becomes "ADR Created"
Create Work Items
- Break down implementation into tasks
- Add to appropriate Statement of Work
- Reference the RFC number in tasks
Track Progress
- Link tasks back to RFC
- Note RFC number in code comments
- Update team on implementation progress