reph

Templates · Engineering

RFC (request for comments) template

A lightweight proposal circulated for comment before a decision: summary, motivation, proposal, alternatives, drawbacks and open questions, with a comment period and decision record

Start with this template →Sign in

Opens on reph with the template ready to start. No account needed; sign in to keep your document.

Use it when

You want feedback on a direction before anyone writes a detailed design or code, and need a dated comment period that ends in a decision

Who it's for

EngineerTech leadEngineering managerProduct manager

Part of a kit

Engineering rituals, step 1 of 7. Propose, decide, build and review: RFC, design doc, ADR, spec, PR description and review checklist.

Filled example

The template filled in for a made-up company, so you can see what good looks like.

RFC: Move service-to-service auth from shared API keys to mTLS

Author: Priya Raman · Date: 2026-09-14 · Status: Open for comment

Northwind's internal services authenticate to each other with long-lived shared API keys. This RFC proposes replacing them with mutual TLS issued by our existing service mesh. We need a go or no-go from platform, payments and data by September 28 so the work can land in Q4 planning.

Summary

Every internal service call would carry a short-lived certificate identifying the calling service, issued and rotated automatically by the mesh. Shared API keys would be retired over one quarter, service by service.

Motivation

  • Two of the last five security findings (SEC-112, SEC-131) were API keys committed to repos or pasted in chat.
  • Rotating a key today takes a coordinated deploy across up to 9 services; we have not rotated the billing key in 14 months.
  • Audit asks "which service called payments at 03:12?" and we cannot answer, because 6 services share one key.

Doing nothing means the next leaked key is a full incident with a multi-team rotation.

Proposal

What changes

  • The mesh issues each workload a 24-hour certificate bound to its service identity.
  • Services authorize callers by identity (an allowlist per endpoint) instead of by key.
  • API keys are removed from the secret store once a service has had zero key-authenticated calls for 14 days.

What stays the same

  • External, customer-facing auth is untouched.
  • Application code that does not handle auth today needs no changes.

Alternatives

Option Pros Cons Why not
Do nothing No work Leaks stay likely, no caller identity Fails the audit requirement
Signed JWTs per call Works outside the mesh Every service must add verification code Twice the engineering effort
Rotate keys monthly Small change Still shared, still no identity Treats the symptom only

Drawbacks

  • Debugging TLS handshake failures is harder than reading a 401.
  • The two batch jobs outside the mesh (ledger export, CSV import) need a sidecar or an exception.
  • About 3 engineer-weeks per team across 7 teams.

Unresolved questions

Review

Comment period: 2026-09-14 to 2026-09-28. Leave comments inline; summarize resolved threads here before deciding.

Reviewer Role Status
Tomas Ek Platform lead Approved
Aisha Bello Payments tech lead Changes requested
Lin Zhou Data engineering Pending

Review by: 2026-09-28

Decision record

Decision Date Decided by Notes
Accepted with changes 2026-09-29 Tomas Ek, Aisha Bello Batch jobs keep scoped keys until Q1; design doc due October 10

The template

Show the blank template

RFC (request for comments)

Author: [your name] · Date: [date] · Status: Open for comment

Two or three sentences: what you propose, and what decision you need by when. A reader who stops here should know whether this affects them.

Summary

The proposal in one paragraph, in plain language. No implementation detail yet.

Motivation

Why now? The problem, who feels it, and the evidence (tickets, incidents, metrics). What happens if we do nothing?

Proposal

The direction you recommend, at the level of "what changes for teams and users". Enough for reviewers to judge it; the detailed how belongs in a design doc if this is accepted.

What changes

Each change a team or user will notice, one line each.

What stays the same

What readers might worry about that this proposal deliberately leaves alone.

Alternatives

Real options you considered, including "do nothing". Reviewers trust a proposal more when the alternatives are argued fairly.

Option Pros Cons Why not
Do nothing

Drawbacks

The honest cost of the proposal: migration effort, new complexity, things that get worse. Write the objections before reviewers do.

Unresolved questions

Questions you want reviewers to weigh in on, and ones you will defer until after the decision.

Review

Comment period: [date] to [review-by date]. Leave comments inline; summarize resolved threads here before deciding.

Reviewer Role Status
Pending
Pending

Review by: [date]

Decision record

Decision Date Decided by Notes
Accepted / Rejected / Deferred

Questions

How is an RFC different from a design doc?
An RFC asks whether and roughly how; the design doc that follows an accepted RFC covers the detailed implementation
How long should the comment period be?
One to two weeks is typical; long enough for every affected team to read it, short enough that it ends in a decision
What if nobody comments?
Silence is not consent; name required reviewers in the Review table and chase them before the review-by date

Fill it with your agent

Connect Claude to reph over MCP, then paste this. The draft arrives as suggestions you accept or reject section by section. How to connect Claude.

Find my reph doc "RFC (request for comments)" with search_docs, then read it with read_doc. Draft Summary, Motivation and Alternatives from the linked tickets, incident reports and any prior design docs or ADRs it references, and list the drawbacks you see in the proposal. File it with suggest_edit, one replace_section op per section (heading line kept) so each can be accepted alone. Ask each open question (unresolved questions and claims you could not source) with add_comment quoting that section's heading line, then call request_review with a one-line summary.

Related templates

Design doc

Context, goals, proposed design, alternatives and rollout for a technical change

EngineerTech leadEngineering manager

ADR

Architecture decision record: one decision, its context and consequences

EngineerTech leadEngineering manager

Technical spec

Implementation-level spec: overview, goals, approach, milestones

EngineerTech lead

API spec

Endpoints, request/response shapes, errors, auth and versioning

EngineerTech lead

Pull request description

What changed and why, the linked issue, how to test, screenshots, risk and rollback, and a reviewer checklist

EngineerTech lead

Code review checklist

What to check before approving a change

EngineerTech lead

Start with this template →Sign in