RFC Specification Writing Skill

This skill automatically activates when writing technical specifications, design documents, or architecture proposals that require structured evaluation and stakeholder review.

When This Skill Activates

•Creating a new technical RFC or design document
•Proposing architectural changes or new systems
•Evaluating technical options objectively
•Documenting technical decisions with rationale
•Writing system design specifications

Core Principles

Objective Technical Analysis

RFCs must maintain strict neutrality when evaluating options:

•
Evidence-Based Evaluation
- •Support claims with data, benchmarks, or documented experience
- •Avoid subjective language ("better", "best", "obvious choice")
- •Present measurable criteria for comparison
•
Balanced Trade-off Analysis
- •Every option has advantages AND disadvantages
- •Document both explicitly for each alternative
- •Avoid dismissing options without clear justification
•
Separation of Facts and Opinions
- •Clearly label assumptions vs verified facts
- •Cite sources for technical claims
- •Distinguish between team preferences and technical constraints
•
Stakeholder Neutrality
- •Present options without advocating for a predetermined choice
- •Let evaluation criteria drive the recommendation
- •Document dissenting opinions fairly

RFC Document Structure

Required Sections

•

Header Metadata

yaml

---
rfc_id: RFC-XXXX
title: [Descriptive Title]
status: DRAFT | REVIEW | APPROVED | IN_PROGRESS | COMPLETED | SUPERSEDED
author: [Name]
reviewers: [List of reviewers with status]
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
decision_date: YYYY-MM-DD (when approved)
---

•
Overview (1-2 paragraphs)
- •What this RFC proposes
- •Why it matters now
- •Expected outcome
•
Background & Context
- •Current state of the system
- •Historical context if relevant
- •Glossary of terms
- •Links to related RFCs or documentation
•
Problem Statement
- •Specific problem being addressed
- •Evidence of the problem (metrics, incidents, user feedback)
- •Impact of not solving (cost, risk, opportunity loss)
•
Goals & Non-Goals
- •Explicit scope boundaries
- •What success looks like
- •What this RFC deliberately does NOT address
•
Evaluation Criteria
- •Measurable criteria for comparing options
- •Weight or priority of each criterion
- •Minimum thresholds where applicable

•

Options Analysis For each option (minimum 2):

markdown

### Option N: [Name]

**Description**: [What this option entails]

**Advantages**:
- [Pro 1]
- [Pro 2]

**Disadvantages**:
- [Con 1]
- [Con 2]

**Evaluation Against Criteria**:
| Criterion | Score/Rating | Notes |
|-----------|--------------|-------|
| ...       | ...          | ...   |

**Effort Estimate**: [Complexity and resources required]

**Risk Assessment**: [Potential risks and mitigations]

•
Recommendation
- •Recommended option with justification
- •How it scores against criteria
- •Acknowledged trade-offs being accepted
•
Technical Design (for approved RFCs)
- •Architecture diagrams
- •API specifications
- •Data models
- •Security considerations
•
Implementation Plan
- •Phases and milestones
- •Dependencies
- •Rollback strategy
•
Open Questions
- •Unresolved technical questions
- •Areas needing further investigation
- •Pending stakeholder input
•
Decision Record
- •Final decision made
- •Date and approvers
- •Key discussion points
- •Conditions or constraints on approval

RFC Lifecycle

code

DRAFT → REVIEW → APPROVED → IN_PROGRESS → COMPLETED
                    ↓
               SUPERSEDED (if replaced by newer RFC)

Status Definitions

Status	Description
DRAFT	Initial writing, not ready for review
REVIEW	Open for stakeholder feedback
APPROVED	Decision made, ready for implementation
IN_PROGRESS	Implementation underway
COMPLETED	Implementation finished
SUPERSEDED	Replaced by newer RFC (link to new RFC)

Evaluation Criteria Framework

Use these standard criteria categories (adapt as needed):

Technical Criteria

•Performance: Latency, throughput, resource usage
•Scalability: Horizontal/vertical scaling, bottlenecks
•Reliability: Fault tolerance, recovery, availability
•Security: Attack surface, data protection, compliance
•Maintainability: Code complexity, debugging, updates

Operational Criteria

•Operability: Monitoring, alerting, incident response
•Deployment: CI/CD integration, rollback capability
•Documentation: Learning curve, knowledge transfer

Business Criteria

•Time to Implement: Development effort, dependencies
•Cost: Infrastructure, licensing, maintenance
•Risk: Technical risk, organizational risk

Neutral Language Guidelines

Avoid

•"Obviously the best choice"
•"Everyone agrees that..."
•"This is clearly superior"
•"The only sensible option"
•Dismissing alternatives as "not worth considering"

Use Instead

•"Based on criteria X, Option A scores higher because..."
•"Option B requires consideration of trade-off Y"
•"The data suggests that..."
•"Stakeholder input indicates a preference for..."
•"Given constraints A and B, Option C is recommended"

Quality Checklist

Before marking RFC as REVIEW:

• All required sections are complete
• At least 2 alternatives are analyzed
• Evaluation criteria are explicit and measurable
• Trade-offs are documented for each option
• Language is objective and evidence-based
• Technical diagrams are included where helpful
• Open questions are clearly listed
• Implementation plan is realistic

Integration with CTO Architect Workflow

When the CTO Architect agent creates technical specifications:

•Use this skill for any significant technical decision
•Follow the template in references/rfc-template.md
•Ensure neutral evaluation of all options
•Link to related PRDs when applicable
•Request review from appropriate technical stakeholders

File Naming Convention

•RFC documents: RFC-XXXX-<short-description>.md
•Example: RFC-0042-api-gateway-selection.md

Directory Structure

code

rfcs/
├── draft/           # Work in progress
├── review/          # Under stakeholder review
├── approved/        # Approved, awaiting or in implementation
├── completed/       # Implementation finished
└── archive/         # Superseded or abandoned
    └── YYYY/

References

•Template: ./references/rfc-template.md
•Evaluation Matrix: ./references/evaluation-matrix.md