ADR

Preserve why a consequential architecture decision exists. Produce a minimal durable record, or conclude that an existing artifact, another document type, or no document is the better home.

Route the request

• Explicit creation: qualify the decision, inspect its evidence and repository conventions, then write and verify the ADR. The request authorizes the warranted record; do not add another creation gate.
• Detected gap: only consider an already settled decision whose rationale is otherwise ephemeral. Finish the active work where safe, recommend the ADR with the concrete missing why, and wait for the user before creating it.
• Existing ADR edit: inspect the record and its history. Apply editorial changes directly; preserve semantic changes through the lifecycle below.
• Existing ADR review: apply the qualification, content, history, and verification checks read-only, then report findings.

1. Qualify the durable rationale

Inspect the decision, relevant code and tests, maintained documentation, temporary design material, existing ADRs, and history before asking for discoverable facts. An ADR is warranted when all of these hold:

• the decision has consequential architectural, operational, compatibility, or security effects and would be meaningfully costly to reverse;
• a reasonable future contributor would question the choice without its context;
• the rationale reflects a real tradeoff or a material external constraint;
• after temporary design artifacts are retired, code and maintained documentation will not preserve the important why.