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

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

Option N: [Name]

Description: [What this option entails]

Advantages:

• [Pro 1]
• [Pro 2]

Disadvantages:

• [Con 1]
• [Con 2]

Evaluation Against Criteria:

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

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

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