ADR Lightweight Template — LADR, Y-Statements, and the Minimum Viable Format

The four formats at a glance

The Y-Statement — one sentence, complete decision

The Y-Statement format originates from Klaus Meffert and Olaf Zimmermann's research on capturing architecture decisions in a consistent single-sentence structure. The template:

In the context of [use case or constraint],
facing [concern or competing concern],
we decided [option chosen],
to achieve [quality or outcome],
accepting [downside or trade-off].

Worked example — database selection:

In the context of the user authentication service handling 10K concurrent sessions,
facing high latency spikes from the external OAuth provider under peak load,
we decided to cache validated OAuth tokens server-side with a 5-minute TTL,
to achieve p95 response times under 100ms during peak traffic,
accepting that forced token invalidation on password change requires an additional cache-flush step.

The Y-Statement forces you to name exactly one concern (the problem you were solving), one trade-off (what you gave up), and one outcome (what you were trying to achieve). These three pieces are the minimum that makes a decision record useful. A decision statement without the trade-off ("we decided to cache OAuth tokens") is not a decision record — it's a description of the current state.

Where Y-Statements belong:

• In the PR description of the implementation PR: "Architecture note (Y-Statement): In the context of …" — this creates a durable record in the PR history without requiring a separate ADR file.
• In meeting notes for decisions made verbally: "Decision made (Y-Statement): …" — captures the decision before it's forgotten.
• As the placeholder before a full ADR is written: paste the Y-Statement into the ADR file as the opening sentence of the Decision section, then expand.

The LADR three-field template — copy-paste ready

The three-field LADR format:

# ADR-NNNN: [Decision statement title — verb phrase, present tense]

## Decision

[What was decided, in two to four sentences. Include the one-sentence reason: the
primary constraint or concern that made this option preferable to the alternatives.
Name at least one alternative that was seriously considered and the one-sentence
reason it was rejected.]

## Consequences

- [Upside: what this decision enables or improves]
- [Downside: what this decision costs or constrains]
- [Optional: what downstream decisions this forces or forecloses]

Worked example — message queue selection:

# ADR-0042: Use RabbitMQ over Apache Kafka for the notification queue

## Decision

We chose RabbitMQ for the cross-service notification queue. Our notification
volume (peak 500 messages/second) is well within RabbitMQ's throughput ceiling
and doesn't require Kafka's distributed log model. Kafka was evaluated and
rejected: Kafka's operational complexity (ZooKeeper or KRaft cluster, topic
partition management, consumer group offset tracking) is not justified at our
scale and would require dedicated ops capacity we don't have. If notification
volume exceeds 50K messages/second or we need persistent event replay for
event-sourcing scenarios, the queue selection should be re-evaluated.

## Consequences

- (+) Simpler deployment: RabbitMQ runs as a single container in development
  and a 3-node cluster in production; no ZooKeeper/KRaft dependency.
- (-) No built-in event replay: RabbitMQ messages are consumed and deleted;
  replay of past notifications requires a separate event store if needed later.
- (-) Throughput ceiling: peak 50K messages/second per vhost; architectural
  rework required if notification volume grows 100x.

Note what the LADR template omits versus Nygard: there is no "Status" field (Status is tracked in the ADR directory index or filename convention, not inside the file) and no "Context" section (the constraint that triggered the decision is embedded in the first Decision sentence rather than having its own section). The trade-off is that readers who encounter this ADR without the surrounding system context may not understand why the constraint existed — which is exactly what a full Context section provides. That's the gap that should be filled retrospectively, six to twelve months after the decision is implemented.

Why "Context" blocks prospective ADR adoption

The Nygard Context section is the most valuable field in a retrospective ADR and the most blocking field for a prospective one. The mismatch is architectural, not motivational.

When you are making a decision in real time, you know the decision and you know the trade-offs. What you don't know yet:

• Which constraints turned out to matter. The decision felt like it was about performance. Six months later, it turns out the real constraint was team skill — you chose the option the team already knew, and performance was a rationalization. That is the honest Context. You can't write it until you've seen which aspects of the decision you keep citing to new hires.
• Which alternatives you should have considered but didn't. Context often reveals overlooked options: "We evaluated RabbitMQ and Kafka, but at the time we didn't evaluate NATS — which would have been a better fit. Context: we were unaware of NATS's JetStream persistence layer." You can only write that sentence after discovering NATS exists.
• The organizational forces that made this urgent. "We made this decision under pressure to ship by the board demo" is a legitimate Context sentence. It explains why a less-ideal option was chosen. Writing that sentence in the moment requires acknowledging a trade-off that's politically uncomfortable at the time.

The lightweight ADR formats acknowledge this reality: they don't ask you to write Context when you don't have it yet. They ask you to write the three things you do know — what you decided, why (in brief), and what it costs — and defer the retrospective narrative to when you have it.

The Context-retrospective workflow

A practical workflow for teams using LADR prospectively:

1. Write LADR at decision time. Three fields, five minutes. File it. Merge the ADR alongside the implementation PR.
2. Set a calendar reminder for six months out. One line in the ADR PR description: "Context audit due: YYYY-MM-DD." (Or use a CI job that opens a GitHub issue on the ADR file six months after merge.)
3. Add Context retrospectively. When the reminder fires, open the ADR and add a Context section above Decision. It will take twenty minutes because you now know what the context actually was. The resulting Context section will be more accurate and more useful than anything you could have written at decision time.

Teams that follow this workflow often find that the retrospective Context write-up surfaces a subtle detail the team forgot: an alternative that was ruled out for a reason that's no longer true, or a constraint that has since changed and might warrant an ADR update. The retrospective Context is not just documentation — it's an audit of whether the decision still holds.

Adding fields over time: the progression from LADR to Nygard-complete

The progression that works for most teams transitioning from LADR to a mature practice:

Phase 1 (months 1–3): three-field LADR

Title + Decision + Consequences. The ADR GitHub Action's auto-numbering and template scaffolding work identically with this format — the LADR template can be set as the default scaffold, and the lint jobs that check for alternatives and consequences content can be enabled even at this phase.

Phase 2 (months 3–6): add Status

The ADR Status field (Proposed → Accepted → Superseded / Deprecated) adds almost no authoring friction (one line of YAML or a single-word heading) but pays significant dividends when the directory grows past 20 ADRs: Status lets a reader scan the directory and immediately see which decisions are still operative versus which have been overridden. Add Status as the second field (after Title, before Decision) so the Status lifecycle is visible at the top of the file.

Phase 3 (month 6+): add Context retrospectively

Six months after an ADR is filed, return to it and add the Context section above Decision. At this stage you know which alternatives you didn't consider, which constraints turned out to be real, and what the organizational forces were. The Context section added retroactively is typically twice as useful as one written prospectively because it reflects what actually happened, not what you thought would happen.

When to skip to Nygard-complete from the start

For retrospective ADRs — the initial batch of 5–10 ADRs documenting decisions already made — write Nygard-complete from the start. You have all the context. The WhyChose extractor can help recover the decision reasoning from the ChatGPT or Claude conversation where the decision was originally worked through, making retrospective Context sections more accurate than memory reconstruction alone.

LADR in practice: the format used by the NYPL Digital team

The most-cited real-world example of LADR in production is the New York Public Library's digital team, which published their ADR directory with the three-field format. Their ADRs follow a slightly different three-field structure: Title + Status + Decision (combining Nygard's Context + Decision into a single narrative paragraph). The NYPL variant demonstrates that "lightweight" doesn't mean a fixed schema — it means removing the structural barriers that stop engineers from filing ADRs in the first place.

The shared insight across all LADR variants: the decision and the primary trade-off are always required. The format argument is only about the supporting metadata (Status, Context, explicit alternatives list) — whether those fields are required at write time or optional/deferred. Teams that require all fields at write time get structurally complete ADRs that are sometimes written long after the decision (because the engineer waited until they had time to do it right) or never written at all. Teams that require only the minimum and allow deferral get ADRs filed closer to the decision, which means the Decision content is more accurate even if the supporting metadata is thin.

How WhyChose fits in

The largest source of LADR prospective ADRs in most engineering teams is AI-assisted decision-making: the ChatGPT or Claude conversation where trade-offs were weighed and a conclusion was reached. That conversation contains the three LADR fields — the decision (the conclusion the thread reached), the primary reason (the constraint or concern the conversation centered on), and the consequences (the trade-offs explicitly named) — but buried in a chat thread rather than structured as an ADR.

The WhyChose extractor identifies decision-shaped conversations in your ChatGPT or Claude export and surfaces them as structured output. For LADR purposes, the extractor output maps directly to the three LADR fields: the decision statement becomes the Title, the rationale thread becomes the Decision paragraph, and the named trade-offs become the Consequences bullets. For retrospective ADRs, the extractor's output provides the raw material for the Context section that LADR defers — the full thread shows which alternatives were considered and what the surrounding context was at decision time.

Get early access

Related questions

Further reading

• ADR adoption guide — how to introduce architecture decision records to a resistant team — the rollout companion that explains why teams resist ADRs (the three real objections behind the stated "overhead"), the retrospective-first rollout approach, and the minimum viable three-field format. This lightweight template page provides the copy-paste artifacts; the adoption guide explains how to get a team to use them.
• The Nygard ADR template (2026 edition) — the canonical five-section format this page's LADR is a stepping stone toward: Title, Status, Context, Decision, Consequences with exact wording guidance for each section and the most common mistakes. The target state for a mature ADR practice once the LADR habit is established.
• MADR (Markdown ADR) template explained — the midpoint between LADR and Nygard-complete: structured YAML frontmatter for machine-readable metadata (status, deciders, date) with narrative prose for the human-readable sections. The natural next step for teams that want GitHub integration and CI tooling after establishing the LADR habit.
• ADR review checklist — what to look for before merging — the 12-item PR-reviewer checklist that applies to both LADR and Nygard formats. Understanding what passes review helps teams write ADRs that meet the quality bar even with the lightweight format — the checklist's Consequences item (requiring at least one downside) applies regardless of which format you use.
• The ADR GitHub Action workflow — CI scaffolding that works with LADR format: auto-numbering and template scaffolding lower the friction for new contributors; the lint jobs that check for alternatives and consequences count can be enabled even for the three-field format. The template the action scaffolds can be set to LADR rather than Nygard-complete.
• Architecture decision record template — comparison and selection guide — the broad head-term comparison page: Nygard, MADR, and arc42 templates side-by-side with a three-question decision tree (How formal is your governance? Do you need CI integration? Are ADRs retrospective or prospective?). LADR and Y-Statements fill in the lower end of the formality spectrum that this comparison page doesn't cover in depth.
• When to write an ADR (and when you shouldn't) — the decision tree that determines which decisions warrant documentation at all: four questions (durable, cross-team, contested, costly to reverse). Pair with this lightweight template page: the when-to-write guide tells you which decisions need an ADR; this page tells you which format to use once you've decided to write one.
• The open-source extractor — recovers decision reasoning from ChatGPT and Claude exports; maps the three LADR fields directly from AI-assisted decision conversations, and provides the raw material for retrospective Context sections when expanding LADR to Nygard-complete.
• ADR vs decision register — scope, mutability, and when you need both — how an ADR directory and a formal decision register differ in audience, mutability, and storage; the complementary pattern for architecture decisions that also require project-level governance tracking.