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

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【/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 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 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】:

# 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 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

# .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

<!-- 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	Static output default; single motion controller	verify-motion.py
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	SKILL.md size limits	lint-skin.py
docs/adr/0005-label-geometry-is-verified.md	Label placement geometry	verify-geometry.py
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	Version bump automation	auto-bump.yml

Summary

• ADRs are the single source of truth for design policy in diagram‑design, referenced in CONTRIBUTING.md and README.md.
• Automated enforcement ties ADRs to CI scripts like verify-motion.py, lint-skin.py, and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}