Requests for Comments
An RFC is a proposal that deserves discussion before a decision is locked in. It's the Synthex artifact for pre-decision conversation — surfacing trade-offs, gathering objections, and producing the context an ADR will eventually cite.
When to write one
Write an RFC when a change is material enough that you want feedback before committing:
- Cross-cutting — it affects multiple subsystems or teams.
- Reversible at high cost — easy enough to ship, hard enough to back out.
- Open-ended — multiple credible approaches and you're not yet sure which is best.
Examples that warrant an RFC:
- Introducing a new shared abstraction or framework convention.
- Changing how authentication, authorization, or audit flows.
- Migrating from one persistence model to another.
- Adopting an opinionated tool that imposes patterns on the codebase.
- Establishing a new SLO or performance budget.
Examples that don't:
- Picking the third-best name for a variable. Cosmetic changes. Anything that fits in a single PR with no meaningful trade-off.
If you can't articulate the alternatives, you don't yet have an RFC — you have a decision in search of cover. Either reduce it to a tactical task, or do the upstream thinking first.
The Synthex convention
RFCs live in docs/specs/rfcs/ (configurable via architecture.rfcs_path). Each RFC is a
numbered markdown file: 0001-shared-cache-layer.md, 0002-billing-events.md, and so on. The
template:
# RFC-NNNN: Short noun-phrase title
**Status:** Draft | Open | Accepted | Rejected | Withdrawn
**Author:** Name (or Architect/PM agents)
**Date:** 2026-MM-DD
**Discussion:** link to issue / chat / PR
## Summary
One paragraph. What is being proposed and why.
## Motivation
What problem are we solving? Why now? What evidence motivates this?
## Proposal
The actual proposal, in enough detail that someone could implement it.
## Alternatives
Each credible alternative considered, with the trade-off that distinguishes it.
## Drawbacks
What does the proposal cost? What does it constrain? What does it make harder?
## Open questions
The unresolved items. The point of the RFC is partly to close these.
## Adoption plan
How does the change land? Phases, migration story, deprecation path.
## References
Prior art, related RFCs, external sources.The Drawbacks and Open questions sections are not optional. An RFC that omits them is advocating, not proposing.
Status flow
Draft → Open → Accepted → (becomes an ADR + spec changes)
↓
Rejected
↓
Withdrawn
- Draft — the author is still shaping the proposal. No reviewers expected yet.
- Open — the proposal is ready for discussion. Reviewers comment, the author iterates.
- Accepted — the proposal is approved. An ADR is written to record the decision, and any specs it modifies are updated.
- Rejected — the proposal was declined, with rationale. The RFC is preserved so the reasoning isn't lost.
- Withdrawn — the author pulled it back, usually because circumstances changed or a better alternative surfaced.
Authoring with the Architect + PM agents
write-rfc/synthex:write-rfc drafts the RFC with the Architect (technical depth) and Product Manager (motivation, scope, success criteria) collaborating on the structure. The draft then runs through a parallel review pass — the same fan-out + consolidation pattern described in the reviewer pipeline.
The review prompts are tuned to surface objections: what could go wrong, what's underspecified, what's the smallest version of this proposal worth shipping. The author addresses severity-high findings before promoting Draft → Open.
RFC vs. ADR
The two are easy to confuse:
- An RFC is open. The decision hasn't been made; comments are welcome; the proposal will evolve.
- An ADR is closed. The decision was made; comments are too late; the document is immutable.
A clean lifecycle: an RFC opens for discussion → the team converges → the proposal is accepted → an ADR records the decision. The RFC stays in the repository as the discussion record; the ADR is the durable answer.
When NOT to RFC
Some teams default to RFC-everything as a hedge against blame. Don't. RFCs have overhead, and overusing them dilutes the signal of the ones that actually need discussion. The right threshold is the one stated above — material change with credible alternatives. If neither condition holds, just do the work.