Long-form docs

Document skeleton

Fixed order works well: Summary → Context & constraints → Options → Decisions → Risks & mitigations → Todos & owners → Appendices. Each decision should link to an ADR or issue for traceability.

• Decisions: chosen option, alternatives, tradeoffs—avoid “obviously better” hand-waving.
• Appendix: glossary, references, superseded content so the body isn’t broken by links.

# RFC document template
---
title: "RFC-042: Adopt event-driven architecture for order processing"
status: draft          # draft | in-review | accepted | rejected | superseded
created: 2026-03-01
authors: ["@alice", "@bob"]
reviewers: ["@carol", "@dave"]
decision_date: ""
---

## TL;DR
One paragraph: what this proposes and why. Decision makers should understand the
core proposal from this section alone.

## Background / Motivation
- Current state: what exists today and why it is insufficient
- Evidence: metrics, incidents, user feedback that justify the change
- Constraints: technical, organizational, or timeline constraints

## Options Considered

### Option A: Event-driven with Kafka (Recommended)
**Pros**: decoupled services, replay capability, horizontal scale
**Cons**: operational complexity, eventual consistency trade-offs
**Estimated effort**: 3 weeks

### Option B: Message queue with SQS
**Pros**: simpler operations, managed service
**Cons**: no replay, limited ordering guarantees
**Estimated effort**: 2 weeks

### Option C: Status quo (keep synchronous REST)
**Pros**: no migration cost
**Cons**: does not address latency and coupling issues

## Decision
**Chosen**: Option A (Event-driven with Kafka)
**Rationale**: replay and audit trail requirements from compliance make Kafka necessary.
**Decision date**: 2026-03-15

## Risks and Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|-----------|
| Team unfamiliar with Kafka | Medium | High | Run workshop; pair with SRE |
| Dual-write complexity | Medium | Medium | Feature flag; gradual migration |

## Implementation Plan / Todos
- [ ] Kafka cluster provisioning (SRE, Week 1)
- [ ] Event schema design and registry setup (Alice, Week 1-2)
- [ ] Producer implementation (Bob, Week 2)
- [ ] Consumer and dead-letter queue (Carol, Week 2-3)

## Timeline
- 2026-03-01: RFC posted for review
- 2026-03-15: Decision finalized
- 2026-04-10: Production rollout

## Appendices
- [Current architecture diagram](./diagrams/current-arch.png)
- [Kafka operational runbook](https://wiki.example.com/kafka)

Review loop

Long docs should be reviewable, mergeable, and searchable. Drafts can be loose; in review, comments anchor to sections; when resolved, update the doc and leave ADR/PR links—not only chat agreement.

  [ draft / outline ]
                    │
                    ▼
            [ structure check: depth ≤ agreed limit ]
                    │
                    ▼
              [ open review / comment on sections ]
                    │
           ┌────────┴────────┐
           ▼                 ▼
    [ need more input? ]   [ ready to merge? ]
           │                    │
           │ yes                │ yes
           ▼                    ▼
    [ update “facts to verify” ]   [ merge body + link ADR/PR ]
           │                    │
           └────────┬───────────┘
                    ▼
            [ publish / archive version ]

# Large RFC implementation: prepare/activate PR splitting strategy

## The Prepare / Activate pattern
When implementing a large design document, split into 3 phases:

### Phase 1: Infrastructure PR (no behavior change)
- Add new data models, database migrations (backward compatible)
- Add new API endpoints (not yet wired to production traffic)
- Add feature flag evaluation code (flag defaults to OFF)
- PR title: "chore(infra): add schema and endpoints for RFC-042"

### Phase 2: Logic PR (behind feature flag)
- Implement core business logic
- Wire new endpoints to the feature flag
- Add comprehensive unit + integration tests
- PR title: "feat(orders): event-driven processing [behind flag]"

### Phase 3: Activate PR (flag on + cleanup)
- Enable feature flag for production traffic
- Remove dual-write code and old synchronous path
- Update documentation and runbook
- PR title: "feat(orders): enable event-driven processing in production"

## Benefits of splitting
- Each PR is reviewable in isolation (< 400 lines)
- Rollback is scoped to one phase
- CI catches regressions at each stage
- Reviewers can focus their domain expertise

Outline depth check

Paste Markdown-style headings (lines starting with #) below to estimate maximum heading depth and counts per level. For technical designs, one H1 for the doc title and body starts at H2—avoid deep trees that break TOC and diffs.