Skip to main content
Use an ADR to preserve one significant architectural choice and its consequences. Use an RFC to circulate a proposal that needs broad discussion before adoption. Use a technical specification to define behavior and design that implementers and maintainers need to keep true.

​
The decision table

​
Use an ADR for “why this choice?”

An ADR captures the context, decision, and consequences of one significant design choice. The ADR community and MADR provide established definitions and formats. Example: “Use a time-bounded database lease for job claims.” The record explains why process locks fail, what alternatives were considered, and what monitoring becomes necessary. Use the ADR template.

​
Use an RFC for “should we adopt this proposal?”

An RFC is a discussion vehicle. It gives reviewers a concrete proposal, motivation, alternatives, compatibility effects, rollout, and open questions. An accepted RFC often produces ADRs for durable architecture choices and a specification for maintained behavior. Example: “Introduce expiring anonymous share links.” Reviewers need to discuss security, user recovery, abuse, migration, and whether expiry is fixed or activity-based. Use the software RFC template.

​
Use a technical specification for “what must remain true?”

A technical specification defines observable requirements, non-goals, design, interfaces, data, failure behavior, security, compatibility, rollout, and verification. It should be maintained when the system changes. Example: “Expired and unknown share links return the same public response, and expired links do not read document content.” That statement can become a requirement with a corresponding integration proof. Use the technical specification template.

​
A useful document chain

Not every change needs the whole chain. A small internal choice may need only an ADR and a pull request. A broad proposal may need all five records. Use the smallest set that leaves no ambiguity about the current authority. For shared discussion, Workspaces uses the same document workflow across plans, specifications, ADRs, RFCs, and handoffs without treating them as separate products. Reviewed July 18, 2026. Written and maintained by the Plannotator documentation team. Format guidance is based on primary ADR sources and common software proposal practice; the example chain is Plannotator’s editorial recommendation.
Last modified on July 19, 2026