Module 5: Architecture Decision Records & Reviews

Primary text: Fundamentals of Software Architecture (Richards, Ford) - ADR chapter, risk matrix, risk storming, and team governance Selective support: Just Enough Software Architecture (Fairbanks) for risk-driven evaluation, Clean Architecture (Martin) and Learning Domain-Driven Design (Khononov) as peripheral references, API Design Patterns (Geewax) for decision examples in API evolution

This guide is the primary teacher. You do not need to read the source books front-to-back to complete this module. You do need to become operationally strong at capturing architecture decisions, running lightweight reviews, and keeping decisions honest over time.

---

Scope of This Module

Architecture is the work of making decisions that are expensive to reverse, and then living with them. This module is about making those decisions visible, defensible, and maintainable.

What it covers in depth:

• what an architecture decision actually is, and how it differs from a design choice
• why decisions need to be written down, beyond "for audit"
• one-way versus two-way doors: how reversibility changes the decision bar
• ADR templates: Michael Nygard's original, MADR, and Y-statements
• the three required sections - context, decision, consequences - and why each one fails silently if missing
• status lifecycle: proposed, accepted, rejected, deprecated, superseded
• ATAM as a full-weight architecture review, and when it is the wrong tool
• risk-driven review in the Fairbanks sense - just enough review for the risk
• lightweight peer review of architecture proposals
• preparing, facilitating, and capturing outputs of a live architecture review
• separating curiosity ("why did you...") from judgment ("this is wrong")
• fitness functions and automated architecture checks as executable governance
• architectural drift and why decisions age out
• guilds and communities of practice as a sustaining structure

What it deliberately does not try to finish here:

• specific architecture styles and patterns (Module 2)
• DDD strategic modeling (Module 3)
• API contract governance (Module 4)
• deep ATAM facilitation for regulated systems (out of scope for this program)

This module sits last in Semester 7 because it governs the decisions every earlier module produces.

---

Before You Start

Answer these closed-book before starting the main path:

1. Name one architectural decision you have seen made, and one design decision. What makes them different?
2. What is a reversible decision versus an irreversible one? Why does the distinction matter for speed?
3. If a teammate asked "why are we using PostgreSQL here and not DynamoDB?", where would you point them if the answer lived nowhere?
4. What does a "lightweight review" actually produce, as artifacts?
5. Give one example of an architectural claim you could enforce with an automated check.

Diagnostic Interpretation

4-5 solid answers

• You have lived with decisions and can start with the concept sequence directly.

2-3 solid answers

• Continue, but expect extra time in Cluster 1 (what a decision is) and Cluster 3 (review methods).

0-1 solid answers

• Skim Module 1 of this semester (architecture fundamentals) before starting. This module assumes you already treat architecture as a first-class concern.

---

What This Module Is For

Most architecture failures are not failures of choice. They are failures of memory, of framing, or of follow-through. A team picks a database, forgets why three years later, and cannot tell when its reasons have expired. A design is "reviewed" in a meeting where nothing is written down, so the next team rebuilds the same bad option.

This module builds the habits that prevent those failures:

• writing a decision so the next engineer can argue with your reasoning, not with your conclusion
• running a review that returns a decision, not a to-do list
• encoding the architectural rules that matter as checks that run without you
• noticing when the rule you wrote down no longer matches reality

By the end, you should feel uncomfortable merging a non-trivial architecture change without either an ADR or a stated reason the change does not warrant one.

---

Concept Map

---

How To Use This Module

Work in order. Each cluster leans on the previous one: you cannot run a review before you can write a decision.

Cluster 1: Architecture Decisions as Artifacts

Order	Concept	Type	Focus
1	What an Architecture Decision Is vs a Design Decision	PRIMARY	Scope, blast radius, and who is affected
2	Why Decisions Need to Be Recorded	PRIMARY	Memory, onboarding, governance, drift defense
3	Reversibility: One-Way vs Two-Way Doors	PRIMARY	Speed vs caution under irreversibility

Cluster mastery check: Given a pending change, can you classify it as architectural or not, decide whether it needs an ADR, and explain the reversibility in one sentence?

Cluster 2: ADR Mechanics

Order	Concept	Type	Focus
4	ADR Templates: Nygard, MADR, Y-Statement	PRIMARY	What each template emphasizes and when to pick which
5	Context, Decision, Consequences: The Three Required Sections	PRIMARY	What fails when any of the three is missing
6	Superseding, Amending, and Status Lifecycle	SUPPORTING	How ADRs age: status transitions and how to kill a decision

Cluster mastery check: Can you write a 1-page ADR in under 30 minutes, correctly using one of the three templates, including non-trivial consequences?

Cluster 3: Architecture Review Methods

Order	Concept	Type	Focus
7	ATAM (Architecture Tradeoff Analysis Method) Sketch	PRIMARY	Utility trees, scenarios, risks, sensitivity and tradeoff points
8	Risk-Driven Review and RCDA-Style Prioritization	PRIMARY	How much review a change deserves, justified by risk
9	Lightweight Peer Review of Architecture Proposals	PRIMARY	Async and sync peer review flows, review bar, review fatigue

Cluster mastery check: Given an architecture proposal, can you pick the correct review method and justify the choice in one paragraph?

Cluster 4: Running Architecture Reviews in Practice

Order	Concept	Type	Focus
10	Preparing a Review: Package, Agenda, Participants	PRIMARY	What goes in the review package and who must be in the room
11	Facilitation: Separating Curiosity From Judgment	PRIMARY	Techniques for keeping the review from turning into a defense
12	Outputs: Decisions, Followups, Captured Risks	SUPPORTING	What must come out of the review, in writing, before it ends

Cluster mastery check: Can you run a 60-minute review that ends with a decision on the page and no open loose threads?

Cluster 5: Architecture Decisions Over Time

Order	Concept	Type	Focus
13	Fitness Functions and Automated Architecture Checks	PRIMARY	Translating an architectural claim into a running test
14	Architectural Drift and How Decisions Age	PRIMARY	Detecting when an ADR is lying, and what to do about it
15	Building an Architecture Guild / Community of Practice	SUPPORTING	Sustaining review quality without becoming a gate

Cluster mastery check: Can you take one architectural claim your team has made, and either implement a fitness function for it or write a one-page justification for why it cannot be automated yet?

Then work these practice pages:

Order	Practice path	Focus
1	ADR Writing Workshop	Write, critique, and rewrite ADRs for real recent decisions
2	Mock Architecture Review	Run a lightweight peer review on a teammate's ADR, as both author and reviewer
3	Fitness Function Design	Turn an architectural rule into an automated check
4	Decision Lifecycle Map	Trace a superseded decision from proposed to replaced, with artifacts

Use Module Quiz after the concept and practice path. Use Reference and Selective Reading and Learning Resources only for targeted reinforcement.

---

Learning Objectives

By the end of this module you should be able to:

1. Distinguish architecture decisions from design decisions by scope, blast radius, and cost of reversal.
2. Write an ADR in Nygard, MADR, or Y-statement form and state which template you used and why.
3. Classify a pending decision as one-way or two-way and calibrate your review effort accordingly.
4. Capture context, decision, and consequences so that a reader 18 months later can argue with the reasoning, not just the conclusion.
5. Move an ADR through its lifecycle correctly: propose, accept, reject, deprecate, supersede.
6. Sketch an ATAM-style utility tree for a system and identify its sensitivity and tradeoff points.
7. Pick a review method (ATAM, risk-driven, lightweight peer) and justify the pick in one paragraph.
8. Prepare an architecture review: package, agenda, stakeholders, expected outputs.
9. Facilitate a review that separates curiosity from judgment and ends with a written decision.
10. Design at least one fitness function for an architectural claim your team cares about, and identify at least one claim that cannot yet be automated.

---

Outputs

• at least 3 complete ADRs written for real decisions (one in each template form)
• one critique of an ADR from another team or an open-source project, in writing
• a mock review transcript (your team or fictional) that ends with a recorded decision, followups, and risks
• at least one fitness function implemented and running against a real codebase
• a drift log: for one subsystem, at least 3 places where reality diverges from a recorded decision, with your diagnosis
• a lifecycle trace of a superseded decision, showing the original ADR, the superseding ADR, and what prompted the change
• a short memo on when not to write an ADR ("ADR bureaucracy") with at least three concrete examples
• a mistake journal on decisions-without-consequences, including two rewritten examples

---

Completion Standard

You have completed Module 5 when all of these are true:

• you can produce an ADR for any non-trivial architecture change in under 30 minutes of focused work
• you can run a 60-minute review that ends with a decision in writing
• you have at least one fitness function running on a real codebase, gated in CI
• you can say, for a given team, which decisions should be one-way and which can be two-way
• you can point to at least one decision you superseded, with both ADRs still present
• you treat "no ADR" as an explicit choice, not as a default

If you have written ADRs but cannot name consequences for any of them, the module is not complete.

---

Reading Policy

• Concept pages are the main path.
• Local book chunks are selective reinforcement, not a second syllabus.
• Read only if stuck means try the concept page, write the drill, and attempt the kata first.
• Optional deep dive means additional context, not required progression.
• Because this module is about writing, expect to write more than you read. Each concept page ends with a small artifact you should produce yourself.

---

Suggested Weekly Flow

Day	Work
1	Concepts 1-3, classify 5 recent team decisions as architectural / design / neither
2	Concepts 4-6, write one Nygard ADR for a past decision
3	Practice 1 (ADR Writing Workshop)
4	Concepts 7-9, read one real ATAM case study linked from Resources
5	Concepts 10-12, prepare a mock review package for a teammate's proposal
6	Practice 2 (Mock Architecture Review)
7	Concepts 13-15, list 3 candidate fitness functions for your current system
8	Practice 3 (Fitness Function Design): ship one into CI
9	Practice 4 (Decision Lifecycle Map), quiz
10	Drift audit on one subsystem, supersede one ADR, clean mistake journal

---

Reference

If you need exact links into the local chunked books, use Reference and Selective Reading.

---

Rich Learning Pages

Worked Examples | Guided Labs | Case Studies | Mistake Clinic | Reading Guide | Capstone Thread

---

Model Artifact Calibration

For architecture decision evidence, compare your record to the ADR model artifact.