rfc-specification

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:

1. Evidence-Based Evaluation

   • Support claims with data, benchmarks, or documented experience
   • Avoid subjective language ("better", "best", "obvious choice")
   • Present measurable criteria for comparison

2. Balanced Trade-off Analysis

   • Every option has advantages AND disadvantages
   • Document both explicitly for each alternative
   • Avoid dismissing options without clear justification

3. Separation of Facts and Opinions

   • Clearly label assumptions vs verified facts
   • Cite sources for technical claims
   • Distinguish between team preferences and technical constraints

4. 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

1. Header Metadata

   ---
   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)
   ---
   

2. Overview (1-2 paragraphs)

   • What this RFC proposes
   • Why it matters now
   • Expected outcome

3. Background & Context

   • Current state of the system
   • Historical context if relevant
   • Glossary of terms
   • Links to related RFCs or documentation

4. Problem Statement

   • Specific problem being addressed
   • Evidence of the problem (metrics, incidents, user feedback)
   • Impact of not solving (cost, risk, opportunity loss)

5. Goals & Non-Goals

   • Explicit scope boundaries
   • What success looks like
   • What this RFC deliberately does NOT address

6. Evaluation Criteria

   • Measurable criteria for comparing options
   • Weight or priority of each criterion
   • Minimum thresholds where applicable

7. Options Analysis For each option (minimum 2):

   ### 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]
   

8. Recommendation

   • Recommended option with justification
   • How it scores against criteria
   • Acknowledged trade-offs being accepted

9. Technical Design (for approved RFCs)

   • Architecture diagrams
   • API specifications
   • Data models
   • Security considerations

10. Implementation Plan

    • Phases and milestones
    • Dependencies
    • Rollback strategy

11. Open Questions

    • Unresolved technical questions
    • Areas needing further investigation
    • Pending stakeholder input

12. Decision Record

    • Final decision made
    • Date and approvers
    • Key discussion points
    • Conditions or constraints on approval

RFC Lifecycle

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:

1. Use this skill for any significant technical decision
2. Follow the template in references/rfc-template.md
3. Ensure neutral evaluation of all options
4. Link to related PRDs when applicable
5. 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

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