ADR Authoring

Architecture Decision Records for capturing design rationale. ADRs supply the temporal dimension — decisions over time — that structure-only views (C4) miss.

Start with Repository Conventions

1. Read the repository's agent instructions, contributing guide, ADR index, template, and a few recent records before drafting. Reuse the established location, numbering, headings, status vocabulary, approval process, and amendment policy.
2. Treat this skill's layouts and templates as fallbacks only. Do not move, renumber, rename, or rewrite existing ADRs to fit the skill. If local conventions conflict, preserve the existing records and identify the specific conflict before changing the convention.
3. If no convention exists, use a flat docs/adr/ directory, stable sequential identifiers, a small index, and a lightweight Nygard template (MADR when option analysis needs more structure). Read references/project-setup-guide.md only when establishing a new decision log.
4. Read references/adr-to-pyramid-mapping.md only if the project already uses artifact pyramids or the user requests that organization. Index links can provide layered navigation without relocating canonical records.

Decision, Approval, and Evidence

Keep these three facts distinct, using the repository's existing fields or linked records:

• Proposal: What is recommended, why, alternatives, consequences, and unresolved questions. A draft or recommendation is not an accepted decision.
• Decision authority and scope: Who approved what, when, and for which environment or stage. Approval to experiment permits the bounded experiment; it does not establish production adoption. An accepted ADR may authorize only an experiment if that scope is explicit. Do not invent a decider, date, or broader approval.
• Implementation evidence: Links to changes, checks, observed results, and remaining gaps. Acceptance does not prove implementation; passing a prototype check does not prove production readiness. Label a validation plan as planned until results exist.