adr.crastinating.pro
Lightweight1 sections · ~50 words

Y-Statement

Olaf Zimmermann, 2018

A single sentence with seven slots. Forces you to name the option, the constraint, the consequence — in one breath.

Use it when

  • You want a one-line decision register that humans actually read.
  • You're capturing many small decisions per week and the overhead of full ADRs would kill the practice.
  • You're documenting decisions inside a larger artifact (RFC, design doc) that already has the long context.

Avoid when

  • The decision has multiple options worth comparing — Y-Statement collapses to one chosen option.
  • The consequences section needs more than a clause.

Strengths

  • Fits in a slack message. Reviewers actually read all of it.
  • Forces the team to name the constraint and the cost in the same sentence — no smuggling.
  • Composes: a sequence of Y-Statements is a decision log.

Weaknesses

  • No structure for alternatives, so reviewers can't see what was rejected.
  • Fragile: a clumsy fill-in produces a sentence that's grammatically broken.

Sections

1 required · 0 optional

Minimum viable structure. The format that survives daily use.

  1. 01

    The Y-Statement Template

    Required

    One sentence, seven slots. Fill each slot literally; if a slot doesn't apply, the decision probably needs a richer template.

    In the context of [use case], facing [concern], we decided for [option] and against [alternative], to achieve [quality], accepting [consequence].

Worked example

A real ADR written in the Y-Statement format. Copy the markdown and adapt it.

Y-Statement: feature-flag provider

Status: Accepted (2026-04-22)

In the context of shipping the operator console behind progressive rollout, facing the need for typed flag definitions and per-team override semantics, we decided for Vercel Edge Config + a thin typed wrapper and against LaunchDarkly and PostHog feature flags, to achieve sub-50ms read latency at the edge with no extra vendor on our SOC 2 scope, accepting that we own the rollout-percentage UI ourselves and lose LaunchDarkly's audit trail for one quarter.

Field of application

Honest accounts of where this template was the right shape — and where it wasn't.

Tags:lightweightone linerregister