Part 1 · 1 chapters · ~8 min

RFCs and Design Review

When a change needs an RFC, a template that forces trade-offs, early readers, named required reviewers, time-boxed review, design review meetings that resolve open questions, decision rights, disagree-and-commit, ADRs, and reviewing others' designs well.

Writing it down first

code

# RFC-212: Move payout status updates from polling to webhooks
Status: In review · Author: … · Approver: … · Required reviewers: security, ledger, mobile
## Problem        Polling rails every 30 s costs $2.1k/month and delays status by up to 30 s.
## Constraints    Rails differ: 3 support webhooks, 2 do not. Must not lose a status update.
## Options        A) keep polling  B) webhooks + polling fallback  C) webhooks only
## Proposal       B, with signature verification and a reconciliation job (Ledgers P6).
## Risks          Forged webhooks (mitigation: HMAC + IP allow-list); missed webhooks (fallback poll).
## Rollout        Per rail behind a flag; compare webhook vs polled status for 2 weeks.
## Open questions Retention of raw webhook payloads? (needs data protection input)

needs an RFC	does not
new service, new datastore, new language	internal refactor inside one service
public or cross-team API changes	bug fixes
anything touching money movement, auth or personal data	dependency upgrades with no behaviour change
migrations affecting other teams	experiments behind a flag with an end date

Reviewing well: ask about failure modes, rollout and rollback, ownership and cost; separate blocking concerns from preferences, and say which is which.

AN RFC FROM DRAFT TO DECISION

write, review, decide, record

swipe the figure sideways, or tap expand for full screen

1/4

draft

Start with the problem and constraints, then options with trade-offs, then the proposal. A reader should be able to disagree with the proposal using only the document.

problem before solutionoptions with trade-offs