ADR Writing Stinger

Architecture Decision Records (ADRs) are the smallest useful unit of institutional memory. This Stinger encodes everything needed to author, govern, and maintain an ADR corpus: the Nygard canonical format, the MADR and Y-statement variants, the supersession lifecycle, lightweight tooling (Log4brains, adr-tools), and the "decisions, not docs" discipline that keeps ADR logs scannable and trustworthy across years of codebase evolution.

---

When to use this stinger

Activate when the user:

• Says "write an ADR", "record this decision", "document our architecture choice", "create an ADR for X"
• Wants to supersede an existing ADR ("we changed our minds about X", "supersede ADR-007")
• Needs to set up an ADR log from scratch ("we've never done ADRs before")
• Asks about tooling ("should we use Log4brains or adr-tools?", "how do I generate ADR HTML?")
• Wants to use ADRs for onboarding ("how do new engineers read our ADR log?")
• Asks about format choices ("Nygard vs MADR vs Y-statements?")

Do NOT activate for:

• General documentation site architecture → library-wasp-drone
• Per-entity code extraction into a wiki → wiki-wasp-drone
• Security review of an architectural decision → security-wasp-drone (hand off after authoring)

---

Playbook

Task	Guide
Choose the right ADR format	guides/00-principles.md
Write a Nygard-style ADR	guides/01-nygard-format.md
Write a MADR-style ADR	guides/02-madr-format.md
Write a Y-statement ADR	guides/03-y-statements.md
Supersede or deprecate an ADR	guides/04-supersession-workflow.md
Set up adr-tools or Log4brains	guides/05-tooling-integration.md
Use the ADR log for onboarding	guides/06-adr-as-onboarding-tool.md

For a worked end-to-end example, see examples/nygard-from-pr.md.

For blank templates, see templates/nygard.md, templates/madr.md, and templates/y-statement.md.

---

Core principles

1. Decisions, not docs

An ADR captures a closed, consequential decision, one that is hard or expensive to reverse and that future engineers will want to understand. It is NOT:

• A design proposal (use an RFC or PRD instead)
• A meeting summary (use a shared doc)
• A description of how something works (use the wiki)
• A changelog entry (use CHANGELOG.md)

The test: "If I delete this ADR, does the team lose understanding of why the codebase is the way it is?" If yes, write it. If no, do not.

2. Four required questions (Nygard canonical)

Every ADR must answer:

1. What is the architectural context? (forces at play, constraints, the problem)
2. What decision did we make? (the concrete, stated choice, no weasel words)
3. What are the consequences? (positive, negative, neutral, the trade-offs accepted)
4. What alternatives were considered and rejected? (and why)

3. Sequential numbering is permanent

ADR numbers are forever. They appear in commit messages (ADR-0012), code comments, PR descriptions, and onboarding docs. Never reuse, never renumber, never skip. A "deleted" ADR becomes Status: Deprecated with an explanation.

4. Supersession is bidirectional

When ADR-0025 supersedes ADR-0012:

• ADR-0025 must say Supersedes: ADR-0012 in its header
• ADR-0012 must say Status: Superseded by ADR-0025

Both links must be present. One-directional supersession breaks the audit trail.

5. Status lifecycle

Proposed → Accepted → Superseded (by ADR-NNNN)
                    → Deprecated  (rationale required)
         → Rejected  (rationale required)

A Proposed ADR is in-flight. Never reference a Proposed ADR from code or other ADRs until it reaches Accepted. Never write Proposed ADRs for decisions already made.

---

Format comparison matrix

Criterion	Nygard	MADR	Y-statement
Length	1 to 2 pages	2 to 4 pages	1 to 5 sentences
Sections	Context, Decision, Consequences	Title, Status, Context, Decision, Consequences, Pros, Cons, Alternatives	Single sentence with embedded structure
Best for	Most team decisions	Decisions needing explicit trade-off tables	Quick records, ADR log summaries
Tooling	adr-tools (native)	MADR template repo	Any markdown
Recommended default	Yes	When alternatives are complex	As supplement to Nygard/MADR

Recommendation: use Nygard as the default. Switch to MADR when the team needs explicit pros/cons tables (common in multi-stakeholder decisions). Use Y-statements as a one-liner summary inside Nygard/MADR, not as a standalone format.

---

Tooling at a glance

adr-tools (npryce/adr-tools)

The original CLI. Creates Nygard-format ADRs, handles supersession linking, generates a table of contents.

adr init docs/decisions                       # initialize ADR log
adr new "Append-only version-bump for embeddings"   # creates docs/decisions/0001-append-only-version-bump.md
adr new -s 1 "In-place UPDATE for embeddings"       # creates 0002, supersedes 0001
adr generate toc                              # regenerates table of contents

Log4brains (thomvaill/log4brains)

Static-site generator for ADR logs. Renders a searchable HTML knowledge base from a markdown ADR corpus. Now at v1.1.0 (December 2024). Supports mono-repo and multi-package layouts.

npx log4brains init              # interactive setup, generates .log4brains.yml
npx log4brains preview           # live preview at localhost:4004
npx log4brains build             # output to .log4brains/out/
npx log4brains adr new "..."     # create ADR and open editor

For tooling setup details, see guides/05-tooling-integration.md.

---

References to research

The research folder was populated by scripture-historian at normal depth (15 files, 12 external source notes). Key sources (source-repository research, not shipped with the plugin):

• Nygard original (2011, canonical): research/external/01-nygard-original.md (source-repository research, not shipped with the plugin)
• Practitioner guides 2025-2026: research/external/02-specsource-2026.md, research/external/03-docsio-2026.md, research/external/04-archyl-2026.md (source-repository research, not shipped with the plugin)
• Format comparison (arXiv 2026 empirical study): research/external/07-arxiv-2026-adr-comparison.md (source-repository research, not shipped with the plugin)
• Log4brains v1.1.0: research/external/09-log4brains-github.md (source-repository research, not shipped with the plugin)
• Google Cloud enterprise patterns: research/external/11-google-cloud-adrs.md (source-repository research, not shipped with the plugin)
• Full index: research/index.md (source-repository research, not shipped with the plugin)

The shipped executive summary is research/research-summary.md.

---

Part of The Wasp Nest, curated by Mario Aldayuz a.k.a @thenotoriousllama.