Write an Architecture Decision Record

Capture why a consequential technical choice was made so it can be revisited. Adapted from Addy Osmani's documentation-and-adrs workflow; see the bundled license and repository third-party notice.

Route precisely

• Use when asked to document an architectural decision or create or update an ADR.
• Use review-arch to assess whether a system structure is sound, review-spec to judge a proposal, and audit-docs to find documentation drift without editing.
• Do not create an ADR for every implementation detail, or silently adopt a decision the user has not made.

Establish the decision

Read repository instructions, existing ADR naming and status conventions, the motivating requirement, current architecture, and any prior superseded decision. Identify the decision maker and date when available; otherwise leave them explicit rather than inventing them. Separate an accepted decision from a proposal awaiting selection.

Write the record

Use the repository's existing format. If none exists, include a concise title, status, date or date-needed marker, context and constraints, decision, credible alternatives, consequences, and follow-up validation. State tradeoffs and rejected options fairly, including the condition under which the decision should be revisited. Link evidence and affected contracts; avoid duplicating implementation documentation or unsupported performance claims.

Verify and report

Check the record against current code, specification, and neighboring ADRs for contradictions and broken links. If the decision is pending, show the unresolved choice without marking it accepted. Report the file or chat artifact, source evidence, status, and any follow-up that remains; do not imply the system has already been changed by writing an ADR.