# Architecture Decision Records (ADRs) in the Diagram‑Design Project: Purpose and Implementation

> Discover the purpose and implementation of Architecture Decision Records ADRs in the diagram-design project. Understand how ADRs serve as authoritative design policy records for improved development.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: architecture
- Published: 2026-09-05

---

**Architecture Decision Records (ADRs) are version‑controlled markdown files that capture settled design policies, providing an authoritative source of truth that is referenced in code, CI checks, and contributor documentation throughout the repository.**

In the **cathrynlavery/diagram-design** repository, ADRs serve as the backbone of the project's design policy framework. Each ADR documents the context, decision, and consequences of a specific architectural choice, making design intent transparent and enforceable across the entire codebase.

## Why ADRs Matter for Design Policy

The project treats ADRs as living documents that bridge high‑level design decisions with day‑to-day implementation. According to the source code, contributors are explicitly instructed to "read the relevant ADR before relitigating one" in [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md)【/cache/repos/github.com/cathrynlavery/diagram-design/main/CONTRIBUTING.md】. This prevents repeated debates over settled questions and establishes clear accountability for architectural changes.

The [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) reinforces this by directing developers to the ADR directory for "settled design decisions"【/cache/repos/github.com/cathrynlavery/diagram-design/main/README.md】, positioning ADRs as the primary reference for understanding why the codebase works the way it does.

## Six Concrete Purposes of ADRs in Diagram‑Design

### 1. Authoritative Source of Truth

ADRs eliminate ambiguity about project standards. When a developer needs to understand a policy, they consult the ADR rather than searching through pull requests or informal discussions.

### 2. Guidelines for Automated Checks

CI scripts directly enforce policies recorded in ADRs. For example, [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) validates motion controller matching according to **ADR 0001**【/cache/repos/github.com/cathrynlavery/diagram-design/main/docs/adr/0001-static-by-default-single-pinned-controller.md】:

```python

# scripts/verify-motion.py – enforce the motion controller policy

# (see ADR 0001 for the rationale)

if not sha256_match(template, motion_script):
    raise ValueError("Motion controller does not match ADR 0001")

```

### 3. Documentation of Design Intent

ADRs capture *why* decisions were made, not just *what* was decided. This preserves institutional knowledge as contributors rotate.

### 4. Change‑Impact Tracking

When new visual types are introduced, the change is recorded in an ADR. **ADR 0007** documents the admission of ten new layout grammars and updates the corresponding verification counters【/cache/repos/github.com/cathrynlavery/diagram-design/main/docs/adr/0007-new-layout-grammars.md】.

### 5. Preventing Policy Regression

The [`test-verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/test-verify-docs-sync.py) test suite references ADRs to detect when implementation drifts from documented policy. This creates a feedback loop that keeps code and documentation synchronized.

### 6. Historical Audit Trail

Each ADR includes a **Status** line and amendment notes. **ADR 0002** demonstrates this with explicit amendments showing when and why rules evolved【/cache/repos/github.com/cathrynlavery/diagram-design/main/docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md】.

## How ADRs Are Referenced in Practice

### In CI Workflows

```yaml

# .github/workflows/auto-bump.yml – automatically bumps plugin versions

# (policy defined in ADR 0009)

name: Auto‑Bump

# ... workflow steps ...

# ADR 0009 – Versions are bumped on main after merge

```

### In Pull Request Descriptions

```markdown
<!-- In a PR description you might write: -->
This change adds a new visual type; see **[ADR 0007 – New layout grammars](
https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0007-new-layout-grammars.md)** for the acceptance criteria.

```

## Key ADR Files and Their Policies

| File | Policy Domain | Enforcement Mechanism |
|---|---|---|
| [`docs/adr/0001-static-by-default-single-pinned-controller.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0001-static-by-default-single-pinned-controller.md) | Static output default; single motion controller | [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) |
| [`docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md) | Semantic pattern constraints | Verification scripts |
| [`docs/adr/0004-skill-md-byte-cap-and-trigger-rich-description.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0004-skill-md-byte-cap-and-trigger-rich-description.md) | [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) size limits | [`lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py) |
| [`docs/adr/0005-label-geometry-is-verified.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0005-label-geometry-is-verified.md) | Label placement geometry | [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) |
| [`docs/adr/0007-new-layout-grammars.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0007-new-layout-grammars.md) | Layout grammar admission criteria | Visual-type counters |
| [`docs/adr/0009-versions-are-bumped-on-main-after-merge.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0009-versions-are-bumped-on-main-after-merge.md) | Version bump automation | [`auto-bump.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/auto-bump.yml) |

## Summary

- **ADRs are the single source of truth** for design policy in diagram‑design, referenced in [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) and [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md).
- **Automated enforcement** ties ADRs to CI scripts like [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py), [`lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py), and [`test-verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/test-verify-docs-sync.py).
- **Version‑controlled history** with status fields and amendments provides complete auditability.
- **Explicit referencing** in code comments and workflow files ensures traceability from implementation to decision rationale.

## Frequently Asked Questions

### What makes an ADR different from regular documentation?

An ADR documents a *decision* with its context and consequences, not just a *procedure*. It includes a status (proposed, accepted, deprecated, superseded), which regular documentation lacks. In diagram‑design, this allows automated tools to track whether policies are active or obsolete.

### How do I create a new ADR in this project?

Follow the pattern in existing files: assign the next sequential number, include **Context**, **Decision**, and **Consequences** sections, and update any verification scripts that enforce the new policy. The project references ADR identifiers in code comments to maintain linkage.

### Can an ADR be changed after acceptance?

Yes, through amendments documented in the ADR itself. **ADR 0002** shows this pattern with explicit amendment notes. However, as [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) states, contributors must read the relevant ADR "before relitigating one"—meaning changes require deliberate consideration, not casual edits.

### Why does the project use ADRs instead of wiki pages or issue discussions?

ADRs are version‑controlled alongside code, making them reviewable, searchable, and referenceable from scripts. The source analysis shows ADR identifiers embedded in Python verification tools, YAML workflows, and test suites—integration that ephemeral formats cannot provide.