Memory

Search first: /mnemonic:search {relevant_keywords} Capture after: /mnemonic:capture {namespace} "{title}"

Run /mnemonic:list --namespaces to see available namespaces from loaded ontologies.

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

code

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:

code

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

markdown

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

markdown

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