Adr Writing Stinger

---
name: "adr-writing-stinger"
description: "Write and govern Architecture Decision Records. Use for new ADRs, supersession, log audits, or ADR tooling. Read guides/ for the decision path."
license: AGPL-3.0-or-later
---

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

```bash
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.

```bash
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:

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

---

*Part of The Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*