rfc

What this skill does

# RFC Skill

Create detailed Request for Comments documents (5-15 pages) for complex architecture changes that require cross-team review, thorough design analysis, implementation planning, and rollback strategies.

**Key principle**: All information comes from the user. Do NOT scan the codebase to discover the problem. The `Read` tool is only for reading user-provided context files (existing ADRs, TSDs, tickets) that the user explicitly shares.

## When to Use an RFC

- Complex architecture changes spanning multiple services
- Changes requiring cross-team coordination and review
- Significant migrations with rollback requirements
- Proposals where implementation phases and sequencing matter
- Anything where a one-pager is too shallow but a TSD is too API-focused

## Workflow

### Phase 1: Gather Context

Parse what the user already provided in their initial request. Extract:
- **Problem**: What's the current pain point?
- **Proposed design**: High-level architecture approach
- **Scope**: Services and teams affected
- **Constraints**: Timeline, compatibility, budget

**Only ask for what's genuinely missing.** If the user described the migration in their request, capture it and move forward.

**Essential questions** (use `references/question-bank.md` patterns, ask only if not already provided):

1. **Current state**: "Walk me through the current architecture/process step by step."
2. **Evidence**: "How do we know this needs to change? What's the evidence?"
3. **Proposed design**: "Describe the target architecture at a high level — what changes?"
4. **Affected services/teams**: "Which services and teams are involved?"
5. **Implementation approach**: "Do you have a phased rollout in mind? Any ordering constraints?"
6. **Migration strategy**: "How do you move from current to target state? Any data migration?"
7. **Rollback plan**: "If this goes wrong after deployment, how do you revert?" (MANDATORY for RFCs)
8. **Alternatives**: "What other approaches did you consider? Why is this preferred?"
9. **Risk areas**: "What are the biggest technical and operational risks?"
10. **Related context** (optional): "Existing ADRs, TSDs, or tickets I should know about?"

**If user seems uncertain**: Offer research assistance via `agent:web-research-specialist`.

**Rich context** (accept at any point):
- File paths → use `Read` tool to load
- Architecture diagrams or descriptions → incorporate
- Pasted content → capture key points

### Phase 2: Generate & Iterate

Once sufficient context is gathered, generate the **complete RFC draft** using the template from `assets/templates/template.md`.

**Content generation rules:**
- Use section headings from `template.md` exactly
- Fill sections with user-provided content
- Use italicized placeholders for missing info: *Describe the migration strategy*
- Do NOT include checkboxes, HTML comments, guidance questions, or quality criteria in output
- The **Rollback Plan** section is MANDATORY — always include it, even if brief

**After presenting the full draft:**
1. Internally validate against `assets/templates/quality-checklist.md` — never show to user
2. Ask targeted follow-ups for gaps (e.g., "The rollback section could use more detail — what's the revert procedure?")
3. Offer diagram generation if architecture is complex
4. Iterate based on feedback
5. Save in requested format

## Document Structure

Key sections (from `assets/templates/template.md`):

| Section | Purpose |
|---------|---------|
| Abstract | Executive summary of the RFC |
| Motivation | Current state, desired state, problem statement |
| Proposed Design | Architecture overview, components, data flow |
| Implementation Plan | Phases, ownership, timeline |
| Migration Strategy | How to transition from current to target state |
| Rollback Plan | **MANDATORY** — how to revert if things go wrong |
| Testing Strategy | Including rollback testing |
| Performance Considerations | Benchmarks, SLAs, load expectations |
| Security Considerations | Auth, data protection, compliance |
| Alternatives Considered | Other approaches and why rejected |
| Risks and Mitigations | Technical and operational risks |
| Open Questions | Unresolved design decisions |
| Success Metrics | How to know the RFC succeeded |
| References | Related docs and external resources |
| Approval | Sign-off section |

## Quality Principles

- **Rollback Plan is non-negotiable** — every RFC must have one
- Require at least 2 alternatives with honest trade-off analysis
- Implementation phases should have clear ownership and sequencing
- Performance and security sections should have concrete numbers, not vague statements
- State your assumptions explicitly

## Visual Aids

Diagrams are highly valuable for RFCs. If the user requests them or if the architecture is complex:
1. Ask what the diagram should show (architecture, data flow, sequence)
2. Invoke `common-engineering:mermaid` skill
3. Integrate into the Proposed Design section

## Integration Points

| Capability | When to Use |
|-----------|-------------|
| `agent:web-research-specialist` | Research industry patterns, technology options |
| `common-engineering:mermaid` | Architecture and sequence diagrams |
| `document-skills:docx` | Export to Word format |
| `document-skills:pdf` | Export to PDF format |

## Reference Files

| File | Purpose |
|------|---------|
| `references/writing-guidelines.md` | Technical writing best practices |
| `references/question-bank.md` | AskUserQuestion patterns for this skill |
| `assets/templates/template.md` | Document structure (use for output) |
| `assets/templates/guidance.md` | Section-by-section guidance (read, never copy to output) |
| `assets/templates/quality-checklist.md` | Internal validation (never show to user) |
| `assets/templates/examples.md` | Completed examples for quality reference |