RFC Review Expertise

Guide comprehensive review and validation of RFC documents using structured assessment frameworks and quality rubrics.

OAK RFC Validation Workflow

Identify RFC  →  Run Automated Checks  →  Manual Review  →  Provide Feedback  →  Verify Fixes

CLI Commands

Review Process

Step 1: Context Gathering

Before reviewing content, gather context:

1. RFC Metadata: Check status, author, creation date, tags
2. Related RFCs: Search for RFCs with similar tags or scope
3. Constitution Alignment: Review oak/constitution.md for applicable standards
4. Codebase Impact: Identify affected modules, services, or components

Step 2: Automated Validation

Run oak rfc validate RFC-{number} to check:

• Required sections present
• Metadata completeness
• No placeholder text remaining
• Proper markdown structure

Step 3: Manual Review

Apply the quality rubric below to assess content quality beyond structural checks.

Quality Assessment Rubric

Score each dimension 1-5 with evidence:

Clarity & Narrative Flow (1-5)

Questions to ask:

• Can someone unfamiliar with the project understand the problem?
• Does the summary accurately reflect the full proposal?
• Are technical terms defined or commonly understood?

Technical Depth & Feasibility (1-5)

Questions to ask:

• Could an engineer start implementation from this spec?
• Are data flows and state changes clearly described?
• Are edge cases and error conditions addressed?

Risk Identification & Mitigation (1-5)

Questions to ask:

• What happens if this fails in production?
• Are operational risks (monitoring, on-call) addressed?
• Who owns each mitigation, and what triggers escalation?

Alignment with Standards (1-5)

Questions to ask:

• Does this follow patterns established in prior RFCs?
• Is the approach consistent with oak/constitution.md?
• Are deviations from standards justified?

Rollout & Measurement Readiness (1-5)

Questions to ask:

• How will we know if this succeeded or failed?
• What's the rollback procedure if issues arise?
• Are metrics defined with baselines and targets?

Issue Severity Classification

Critical (Must Fix Before Progressing)

• Missing required sections (Summary, Motivation, Design)
• Incorrect RFC status for the review stage
• Blocking inconsistencies with adopted standards
• No rollback plan for high-risk changes
• Placeholder text in critical sections

Major (Should Fix Before Approval)

• Ambiguous scope or unclear boundaries
• Weak success metrics (no baselines or targets)
• Alternatives analysis feels superficial or biased
• Risk mitigations lack owners or triggers
• Technical design has significant gaps

Minor (Nice-to-Have Improvements)

• Stylistic inconsistencies
• Could use more examples or diagrams
• Minor formatting or markdown issues
• Additional alternatives could strengthen the case
• More detail in non-critical sections

Structured Feedback Template

When providing feedback, use this structure:

## RFC Review: RFC-{number} - {title}

### Overall Assessment
**Rating**: Ready / Needs Work / Blocked
**Rubric Scores**: Clarity: X, Technical: X, Risks: X, Alignment: X, Rollout: X

### Critical Issues
1. **[Section]**: [Issue description]
   - Evidence: [Quote or reference]
   - Suggested fix: [Specific recommendation]

### Major Issues
1. **[Section]**: [Issue description]
   - Evidence: [Quote or reference]
   - Suggested fix: [Specific recommendation]

### Minor Issues
- [Section]: [Brief issue and suggestion]

### Strengths
- [What the RFC does well]

### Questions for Author
1. [Clarifying question]
2. [Design question]

### Next Steps
- [ ] [Specific action item]
- [ ] [Specific action item]

Review Questions by Section

Summary

• Does it explain the problem, solution, AND expected impact?
• Can a busy stakeholder decide if they need to read more?
• Does it avoid implementation details?

Motivation

• Is there quantitative evidence (metrics, incidents, complaints)?
• Is it clear who is affected and how severely?
• Does it answer "why now?" convincingly?

Goals / Non-Goals

• Are goals measurable with specific numbers and timelines?
• Are non-goals specific enough to prevent scope creep?
• Do goals align with the stated motivation?

Detailed Design

• Could an engineer implement from this spec?
• Are component interactions and data flows clear?
• Are edge cases and error conditions addressed?

Drawbacks / Risks

• Are all obvious risks identified?
• Does each risk have impact, likelihood, AND mitigation?
• Are operational risks (monitoring, on-call) included?

Alternatives

• Are at least 2 alternatives considered?
• Do alternatives have genuine pros (not strawman)?
• Is the rejection rationale clear and evidence-based?

Success Metrics

• Do metrics have baselines AND targets?
• Are there both leading and lagging indicators?
• Can the metrics actually be measured with current tooling?

Rollout Plan

• Are phases clearly defined with criteria for progression?
• Is there a rollback plan with specific triggers?
• Are feature flags or blast-radius controls specified?

Common Review Findings

Re-Review Checklist

After fixes are applied, verify:

• All Critical issues resolved
• Major issues addressed or explicitly deferred with rationale
• Automated validation passes (oak rfc validate)
• Cross-references updated if scope changed
• Status updated appropriately