Y-Statement ADR Format

The Y-Statement format, developed by Olaf Zimmermann, captures architectural decisions in a single structured sentence. It is the most concise ADR format available.

About Y-Statement Format

The Y-Statement format is:

• Concise - Core decision in one sentence
• Structured - Fixed format ensures completeness
• Traceable - Connects decision to context and consequences
• Quick - Minimal documentation overhead

The Y-Statement Structure

Basic Y-Statement

In the context of {use case/user story},
facing {concern/non-functional requirement},
we decided for {option}
and against {other options},
to achieve {quality/goal},
accepting {downside/consequence/trade-off}.

Extended Y-Statement

Adds a "because" clause for additional rationale:

In the context of {use case/user story},
facing {concern/non-functional requirement},
we decided for {option}
and against {other options},
to achieve {quality/goal},
accepting {downside/consequence/trade-off},
because {additional rationale}.

Template Structure

# {NUMBER}. {TITLE}

Date: {DATE}

## Status

{STATUS}

## Decision

In the context of {context},
facing {concern},
we decided for {chosen option}
and against {rejected options},
to achieve {quality goal},
accepting {trade-off}.

## Rationale

{Optional: Expand on the decision with additional context}

## Consequences

{Optional: List specific positive and negative outcomes}

Writing Y-Statements

Fill-in Guide

Placeholder	What to Include	Example
{context}	Use case or scenario	"building a real-time notification system"
{concern}	Quality attribute or requirement	"the need for sub-second message delivery"
{option}	Chosen solution	"WebSockets"
{other options}	Alternatives rejected	"HTTP polling and Server-Sent Events"
{quality}	Goal achieved	"low-latency bidirectional communication"
{trade-off}	Accepted downside	"increased infrastructure complexity"

Complete Example

# 7. Use WebSockets for Real-Time Notifications

Date: 2025-01-15

## Status

Accepted

## Decision

In the context of building a real-time notification system for our
trading platform, facing the need for sub-second message delivery to
thousands of concurrent users, we decided for WebSockets and against
HTTP long-polling and Server-Sent Events, to achieve low-latency
bidirectional communication with efficient connection management,
accepting increased infrastructure complexity and the need for
WebSocket-aware load balancers.

## Consequences

* Good, because notification latency reduced to <100ms
* Good, because server push eliminates polling overhead
* Bad, because load balancer configuration is more complex
* Bad, because connection state management requires additional code

When to Use Y-Statement Format

Best for:

• Quick decision documentation
• Simple, clear-cut decisions
• Decisions with obvious winner
• Teams valuing brevity
• Lightweight ADR processes

Consider other formats when:

• Complex multi-option analysis needed
• Detailed pros/cons documentation required
• Multiple stakeholders need extensive context
• Decision reasoning is nuanced

Y-Statement Best Practices

Writing Tips

• Keep the statement readable as one (long) sentence
• Be specific in each placeholder
• Name concrete alternatives rejected
• State measurable quality goals
• Be honest about trade-offs

Common Mistakes

Mistake	Example	Fix
Vague context	"building our system"	"building the payment processing module"
Missing alternatives	"other options"	"manual processing and third-party service"
Unclear quality	"better performance"	"sub-100ms response time"
Hidden trade-offs	"minor issues"	"monthly maintenance overhead of 4 hours"

Comparison with Other Formats

Aspect	Y-Statement	Nygard	MADR
Length	~1 sentence	3-5 paragraphs	1-2 pages
Structure	Fixed format	Flexible	Flexible
Options	Named in statement	Implicit	Explicit section
Best for	Simple decisions	Quick docs	Complex analysis

Additional Resources

Templates

Template available at: ${CLAUDE_PLUGIN_ROOT}/templates/y-statement/adr-template.md

External Resources

• Y-Statements by Olaf Zimmermann
• Sustainable Architectural Decisions (IEEE Software)