adr-template

name	adr-template
description	Guide and template for authoring and maintaining Architecture Decision Records (ADRs). Captures structural decisions, background context, trade-offs, and compliance verification in lightweight, immutable markdown records to preserve engineering context. Activate when making significant architectural choices, documenting technical trade-offs, proposing major refactorings, or authoring ADRs.
license	Apache-2.0
metadata	{"category":"standards","tags":"adr, architecture, standards, documentation, design","author":"Daniela Petruzalek ([e-mail])","version":"0.1.1","catalog":"https://skills.danicat.dev"}

Architecture Decision Records (ADRs)

Use this skill to write and maintain Architecture Decision Records (ADRs). ADRs are lightweight, plain-text files that capture architectural choices, their context, and their consequences.

---

1. Core Philosophy

Architecture consists of decisions that are hard to change. ADRs prevent two primary engineering problems:

• Context Loss: Future developers often struggle to understand why code was written a certain way, leading to regressions when they remove constraints they do not see. ADRs record the underlying rationale.
• Discussion Decay: ADRs capture the final conclusion and the forces that shaped it, rather than every detail of the debate.

---

2. Rules of ADRs

[!IMPORTANT]

• Keep ADRs lightweight. Limit each record to one or two pages. An ADR is a record of a decision, not a comprehensive design specification.
• ADRs are immutable logs. Do not edit an approved and committed ADR. If a decision changes, write a new ADR and update the status of the old one to "Superseded by ADR-NNNN".
• Document consequences and trade-offs. Every architectural choice has downsides. Explicitly list negative consequences, technical debt, and new constraints.

---

3. Directory and Naming Conventions

Store all ADRs in the project documentation folder:

design/adr/
  ├── 0001-record-architecture-decisions.md
  ├── 0002-use-stdio-mcp-transport.md
  └── 0003-transactional-compiler-gated-editing.md

• File format: Markdown (.md)
• Naming pattern: NNNN-short-descriptive-title.md where NNNN is a sequential four-digit number starting at 0001.

---

4. Standard ADR Template

Use this template when creating an ADR:

# ADR-[Number]: [Active Verb Title]

- Status: [Proposed | Approved | Superseded by ADR-XXXX | Rejected]
- Date: [YYYY-MM-DD]
- Author(s): [Names]
- Deciders: [Names of participants in the decision]

## 1. Context
Describe the current situation, background context, and the problem to solve. What technical, organizational, or operational factors are at play? What constraints apply? State facts objectively.

## 2. Decision
State the chosen architectural path clearly. Explain why this path was selected over alternatives. List the other options considered and the reasons for rejecting them.

## 3. Consequences
Detail the impact of this decision. Explicitly list positive gains, negative trade-offs or constraints, and neutral structural shifts.

## 4. Compliance and Verification
How will the team verify that this decision is respected and implemented correctly? Detail the specific automated tests, pipeline checks, or manual hooks that enforce compliance.

---

5. Verification Checklist

Before finalizing an ADR, verify the following:

• Does the ADR clearly state the forces involved?
• Does it document the alternatives that were discarded?
• Is the tone objective and factual, avoiding unquantifiable words like "perfect", "flawless", or "elegant"?