Summaries of artifacts, templates, practices, and techniques for agile architecting (DPR-mm) and service design (SDPR-nn).

DPR Git Pages HomeArtifacts Index

Artifact/Template: Architectural Decision Record (Y-Statement)

also known as: Why-Statement

A Y-Statement captures decision context, addressed requirement(s), decision outcome, and consequences (good and bad) in a single, structured sentence.

Motivation (Addressed Information Need)

The purpose of this artifact and template is to provide decision rationale (justifications for chosen patterns, technologies, products). Instances of this template answer “why?” questions about an architecture (across viewpoints and perspectives).

Usage (Produced and Consumed When)

Architectural Decisions (ADs) are made by different stakeholders throughout the entire project (or product development): team leads, team members recording group decisions, lead and subsystem architects, DevOps specialists, and so on. For the time being, only the Application Architect and the API Product Owner role are modeled in DPR; decision making and capturing is described in this activity in DPR.

On agile projects, the sprint/iteration review meetings might be a good point in time to gather and discuss decision rationale; daily stand-ups may be used for urgent ones.

Template Structure and Notation(s)

Y-Statements are often captured in plain but structured text (but tables in presentation tools, wiki pages, and modeling tools can also be used):

Y-Statement Template


Wikipedia has this example:

In the context of the Web shop service, 
facing the need to keep user session data consistent and current across instances, 
we decided for the Database Session State Pattern 
(and against Client Session State or Server Session State)
to achieve cloud elasticity, 
accepting that a session database needs to be designed, implemented, and replicated. 


Several options are available:

When embedding ADs in code, custom annotations can be used. For instance, Embedded Architectural Decision Records (e-adr) provides such annotations for Java.

Hints and Pitfalls to Avoid

Origins and Signs of Use

The WH(Y) template for AD records was originally suggested in a SATURN 2012 presentation by Olaf Zimmermann; it has been practiced in a number of projects, for instance at ABB, and taught at HSR/OST since 2013.

The template took inspiration from the decision outcome format suggested by George Fairbanks in his Architecture Haikus, presented at WICSA 2011: The upper part of Y-Statements (“In the context of, facing”) adds feature- and quality-related information to the tradeoff information (“to achieve, accepting that”) in the bottom part also present in Haiku decision outcomes.

A blog post called “Architectural Decisions — The Making Of” provides more historical information, known uses, an additional example, and advice on how to provide convincing justifications.

Instances of this artifact are produced when employing a continuous or stage-based Architectural Decision Capturing practice. The captured rationale (decision justification) should reference one or more non-functional requirements and go hand-in-hand with the Architecture Modeling activities.

Many other templates have been proposed; see activity description for pointers.

More Information

Data Provenance

title: "Design Practice Repository (DPR): ADR-Y"
author: Olaf Zimmermann (ZIO)
date: "09, 09, 2022"
copyright: Olaf Zimmermann, 2020-2022 (unless noted otherwise). All rights reserved.
license: Creative Commons Attribution 4.0 International License