← Back to all projects

DECISION HYGIENE AND ARCHITECTURE MASTERY

In most software projects, architecture isn't designed as much as it happens. A developer chooses a database because they used it before; another adds a library because it was on Hacker News. This is the **Random Walk Architecture**—a series of disconnected, often contradictory choices that lead to a Big Ball of Mud.

Learn Decision Hygiene: From Chaos to Architectural Mastery

Goal: Deeply understand the discipline of Decision Hygiene—the practices and tools that prevent “random walk” architecture. By the end of this journey, you will master how to manage ownership, apply timeboxes to technical spikes, categorize reversibility, and maintain an explicit log of assumptions, ensuring that your software architecture evolves by design rather than by accident.

Why Decision Hygiene Matters

In most software projects, architecture isn’t “designed” as much as it “happens.” A developer chooses a database because they used it before; another adds a library because it was on Hacker News. This is the Random Walk Architecture—a series of disconnected, often contradictory choices that lead to a “Big Ball of Mud.”

Decision Hygiene is the antidote. It acknowledges that:

  1. Context is perishable: Why we chose X over Y is forgotten in 6 months.
  2. Not all decisions are equal: Some are easy to change (Type 2), some are “one-way doors” (Type 1).
  3. Silence is not consensus: Undocumented decisions create “tribal knowledge” that leaves when people do.
  4. Assumptions are hidden bugs: Every design is built on assumptions that might be false.

Understanding this unlocks the ability to lead senior engineering teams, manage multi-year projects, and build systems that don’t collapse under the weight of their own history.

Core Concept Analysis

The “Random Walk” vs. Targeted Evolution

Random Walk Architecture (The Mess):

Start ----> [Decision A]
               |
               v
        [Decision B] <---- (Wait, why did we do that?)
               |
               v
        [Decision C] ----> [Crisis]

Targeted Evolution (The Goal):

[Strategy] ----> [ADR 1: Clear Owner] ----> [Timeboxed Spike]
                                               |
                                               v
[Revision] <---- [Feedback Loop] <---- [Explicit Assumptions]

Fundamental Building Blocks

1. The Architecture Decision Record (ADR)

An ADR is a short text file that captures a single decision, its context, and its consequences. It is the “source of truth” for the why, not just the what.

2. Decision Reversibility (The Amazon Model)

  • Type 1 (Irreversible): High-stakes, hard to undo (e.g., choosing a primary language, switching cloud providers).
  • Type 2 (Reversible): Easy to change (e.g., adding a library, changing a private API). Hygiene Practice: Spend 80% of your time on Type 1, and delegate Type 2 quickly.

3. The Spike & The Timebox

A “Spike” is a task aimed at gathering information. Hygiene Practice: A spike without a timebox is just a rabbit hole. You must define “We will spend 4 hours to answer X; if we don’t know, we stop and regroup.”

4. Explicit Assumptions vs. Implicit Hope

“The database will handle 10k RPS” is an assumption. If it’s not written down, it’s a hope. Hygiene Practice: Map every major component to the assumptions required for it to be the “right” choice.

Concept Summary Table

Concept Cluster What You Need to Internalize
Ownership (RACI) Every decision must have one “Accountable” person. Committees don’t make decisions; owners do.
Context Retention The reason for a decision is more important than the decision itself for future maintainers.
Reversibility If you treat every decision as a “one-way door,” you move too slow. If you treat none as such, you break things.
Timeboxing Perfect information is impossible. You must decide when “good enough” information is reached.
Assumption Tracking Decisions are hypotheses. When assumptions change, the decision must be revisited.

Deep Dive Reading by Concept

Foundations of Architecture

| Concept | Book & Chapter | |———|—————-| | The Architecture Decision Record | “Fundamentals of Software Architecture” by Mark Richards — Ch. 19: “Architecture Decision Records” | | Decision Quality | “Noise” by Daniel Kahneman — Part 1: “Finding Noise” (Applying statistical thinking to human choice) |

Process and Evolution

| Concept | Book & Chapter | |———|—————-| | Reversible Decisions | “The Amazon Way” by John Rossman — Ch. 3: “Are You a Builder?” | | Architecture Spikes | “The Pragmatic Programmer” by Hunt & Thomas — Ch. 3: “Tracer Bullets” | | Evolutionary Design | “Building Evolutionary Architectures” by Neal Ford — Ch. 1: “Software Architecture” |

Essential Reading Order

  1. Foundation (Week 1):
    • Fundamentals of Software Architecture Ch. 19 (ADRs)
    • The Pragmatic Programmer Ch. 3 (Tracer Bullets/Spikes)
  2. Decision Theory (Week 2):
    • Building Evolutionary Architectures Ch. 1 & 2
    • Michael Nygard’s original blog post: “Documenting Architecture Decisions”

Project List

Projects are ordered from fundamental understanding to advanced implementations.

Project 1: The ADR Sentinel (Standardizing the Record)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Go
  • Alternative Programming Languages: Rust, Python, Node.js
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 2. The “Micro-SaaS / Pro Tool”
  • Difficulty: Level 1: Beginner
  • Knowledge Area: CLI Tooling / Workflow Automation
  • Software or Tool: Markdown, Git
  • Main Book: “Fundamentals of Software Architecture” by Mark Richards

What you’ll build: A CLI tool that manages the lifecycle of Architecture Decision Records (ADRs). It should initialize a repository, generate numbered templates, and provide a “status” view of current vs. superseded decisions.

Why it teaches Decision Hygiene: It forces you to think about the schema of a decision. By automating the creation of context, consequences, and status, you make the “right way” to document easier than the “lazy way.”

Core challenges you’ll face:

  • Defining a rigid yet flexible template → maps to Context vs. Decision vs. Consequences
  • Handling decision supersession → maps to Decision Lifecycles (Proposed, Accepted, Superseded, Deprecated)
  • Linking decisions → maps to Understanding how one choice affects another

Key Concepts:

  • ADR Format: Michael Nygard’s Template (blog.cognitect.com)
  • Status Codes: RFC 2119 (Keywords for use in RFCs)
  • Git as a Source of Truth: “Pro Git” Ch. 1 - Scott Chacon

Difficulty: Beginner Time estimate: Weekend Prerequisites: Basic file I/O in your chosen language, familiarity with Markdown.

Real World Outcome

You will have a tool named adr that you can run in any project directory. When you run adr new "Switch to Postgres", it generates a file like 0005-switch-to-postgres.md with pre-filled headers for Context, Decision, and Consequences.

Example Output:

$ adr list
[0001] Accepted: Initial Project Structure
[0002] Accepted: Use SQLite for Local Development
[0003] Superseded by [0005]: Use Manual Memory Management
[0004] Proposed: Implement JWT Auth
[0005] Accepted: Switch to Postgres (Supersedes [0002])

$ adr status
Project Decision Health: 80% (4 Accepted, 1 Proposed)
Recent Changes: [0005] added 2 days ago.

The Core Question You’re Answering

“If the person who wrote this code quits tomorrow, how will I know why they chose this specific library over the more popular one?”

Before you write any code, sit with this question. Code tells you how it works; the ADR tells you why it works that way.

Concepts You Must Understand First

Stop and research these before coding:

  1. Architecture Decision Records (ADRs)
    • What is the difference between an “Accepted” decision and a “Proposed” one?
    • Why do we never delete old ADRs?
    • Book Reference: “Fundamentals of Software Architecture” Ch. 19
  2. Supersession Logic
    • If ADR #5 supersedes ADR #2, what should the status of ADR #2 become?
    • How do you link them so a developer reading #2 knows to go to #5?

Questions to Guide Your Design

Before implementing, think through these:

  1. Metadata Storage
    • Will you store metadata (status, date) in the Markdown frontmatter (YAML) or inside the text?
    • How will the CLI quickly list all ADRs without reading every full file?
  2. User Experience
    • How can you make it impossible for the user to forget to fill out the “Consequences” section?

Thinking Exercise

The Ripple Effect Trace

Imagine a decision: “Use NoSQL for user profiles.” Six months later, the business requires complex relational queries across profiles.

Trace the ADR path:

  • How would you document the “New requirement”?
  • Does the old ADR get deleted? Why not?
  • How does the new ADR reference the failure of the old one’s assumption?

The Interview Questions They’ll Ask

  1. “How do you handle technical debt that arises from decisions made by people no longer on the team?”
  2. “What’s the difference between a design document and an ADR?”
  3. “When is a decision ‘too small’ for an ADR?”
  4. “How do you ensure ADRs stay up to date with the actual code?”
  5. “Can an ADR be changed once it is ‘Accepted’?”

Hints in Layers

Hint 1: The Template Start by hardcoding the standard Nygard template into your app as a string constant.

Hint 2: File Numbering Read the current directory, find the highest number (e.g., 0004), and increment it for the next file.

Hint 3: Linking If the user passes a flag like --supersedes 0002, your code should open 0002.md, change its status to Superseded, and add a link to the new file.

Hint 4: Verification Use a linter approach. Create a command adr lint that checks if any sections in an ADR are empty (e.g., “Consequences: TBD” should fail).

Books That Will Help

Topic Book Chapter
ADR Structure “Fundamentals of Software Architecture” Ch. 19
CLI Design “The Pragmatic Programmer” Ch. 4: “Pragmatic Paranoia”

Project 2: The Reversibility Scorecard (Type 1 vs Type 2)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Python
  • Alternative Programming Languages: TypeScript, Ruby
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 3. The “Service & Support” Model
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Decision Theory / Risk Assessment
  • Software or Tool: Risk Matrix, Survey Logic
  • Main Book: “The Amazon Way” by John Rossman

What you’ll build: A survey-based tool that takes a proposed decision and calculates a “Reversibility Score.” It asks about migration cost, vendor lock-in, and team training time to determine if it’s a Type 1 (One-way door) or Type 2 (Two-way door).

Why it teaches Decision Hygiene: It trains your intuition. You learn that “choosing a CSS framework” is usually Type 2, while “choosing a multi-region database strategy” is Type 1. This prevents “analysis paralysis” on small things.

Core challenges you’ll face:

  • Defining the scoring algorithm → maps to Weighting factors like cost vs. time vs. complexity
  • Handling uncertainty → maps to How ‘I don’t know’ affects the score
  • Exporting the ‘Why’ → maps to Generating a summary of why it’s high-risk

Key Concepts:

  • Type 1 vs Type 2 Decisions: Jeff Bezos’ 2015 Letter to Shareholders
  • Cost of Change Curve: “Extreme Programming Explained” - Kent Beck
  • Vendor Lock-in Analysis: “Cloud Strategy” - Gregor Hohpe

Difficulty: Intermediate Time estimate: 1 week Prerequisites: Logic flow/conditionals, basic data persistence (JSON/SQLite).

Real World Outcome

A web or CLI tool where you input details about a technical choice, and it outputs a risk profile.

Example Output:

Decision: "Adopt Kubernetes for our 3-person startup"

Scores:
- Migration Cost: 9/10
- Vendor Lock-in: 4/10
- Team Skill Gap: 10/10
- Reversibility: 2/10

Result: TYPE 1 DECISION (Irreversible)
Recommendation: This is a ONE-WAY DOOR. Do not proceed without a 2-week technical spike and executive sign-off.

The Core Question You’re Answering

“Is this decision a ‘one-way door’ that will haunt us for years, or a ‘two-way door’ we can walk back next month?”

Project 3: The Spike Timeboxer (Capping Research)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: JavaScript/Node.js
  • Alternative Programming Languages: Go, Python
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 2. Micro-SaaS
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Project Management / Productivity Tools
  • Software or Tool: Trello/GitHub Issues API
  • Main Book: “The Pragmatic Programmer” by Hunt & Thomas

What you’ll build: A tool that integrates with your task manager (like GitHub Issues) to manage “Spikes.” It forces the user to define a “Goal” and a “Hard Stop” time. When the time is up, it forces the user to post a “Result” before the issue can be closed.

Why it teaches Decision Hygiene: It enforces the “Timebox” rule. Most technical research fails because it has no end-date. This project teaches you that no answer is still an answer once the timebox expires.

Project 5: The RACI Oracle (Ownership Clarity)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: TypeScript
  • Alternative Programming Languages: Go, Ruby
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 3. Service & Support Model
  • Difficulty: Level 1: Beginner
  • Knowledge Area: Organizational Design / Governance
  • Software or Tool: YAML, Mermaid.js
  • Main Book: “Fundamentals of Software Architecture” by Mark Richards

What you’ll build: A tool that parses a YAML file containing project roles and technical components, then generates a RACI (Responsible, Accountable, Consulted, Informed) matrix. It should specifically check for “Ambiguous Accountability” (more than one Accountable person per decision).

Why it teaches Decision Hygiene: It enforces the rule: “If everyone is responsible, no one is.” You learn that a decision needs a single throat to choke (Accountable) to prevent it from stalling in committees.

Core challenges you’ll face:

  • Defining the validation rules → maps to Ensuring exactly one ‘A’ per row
  • Visualizing the matrix → maps to Generating tables or graphs from data
  • Handling role turnover → maps to Mapping roles to individuals

Key Concepts:

  • RACI Matrix: Project Management Body of Knowledge (PMBOK)
  • Single Point of Accountability: “Turn the Ship Around!” - L. David Marquet
  • Mermaid Graph Generation: Mermaid.js documentation

Difficulty: Beginner Time estimate: Weekend Prerequisites: Basic data parsing (YAML/JSON).

Real World Outcome

A generated Markdown table or Mermaid diagram for your project’s README.md.

Example Output: | Decision Area | Lead Dev (A) | Backend (R) | DevOps (C) | CEO (I) | |—————|————–|————-|————|———| | Database Schema| X | R | C | I | | Cloud Provider | X | I | R | I | | API Design | R | X | C | I |

Validation Warning: ERROR: Decision "Cloud Provider" has 2 Accountable roles (Lead Dev, CEO). Decisions must have exactly one Accountable person.

The Core Question You’re Answering

“When this project is 3 months late because the architecture is messy, who is the ONE person responsible for the choices that led us here?”

Project 6: The Drift Detector (Docs vs. Reality)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Python
  • Alternative Programming Languages: Rust, JavaScript
  • Coolness Level: Level 4: Hardcore Tech Flex
  • Business Potential: 4. Open Core Infrastructure
  • Difficulty: Level 3: Advanced
  • Knowledge Area: Static Analysis / Infrastructure as Code
  • Software or Tool: AST (Abstract Syntax Trees), Terraform/K8s YAMLs
  • Main Book: “Building Evolutionary Architectures” by Neal Ford

What you’ll build: A tool that scans your codebase (or infra-as-code) and compares it against your ADRs. For example, if ADR #12 says “We use Postgres,” but the tool finds a docker-compose.yml with MongoDB, it flags an “Architectural Drift.”

Why it teaches Decision Hygiene: It addresses the “Liar’s Paradox” of documentation. You learn that documentation is only hygienic if it reflects reality. This project bridges the gap between design and implementation.

Core challenges you’ll face:

  • Extracting “Intent” from ADRs → maps to Regex or NLP on Markdown
  • Extracting “Reality” from code → maps to Parsing config files or using ASTs
  • Dealing with False Positives → maps to Understanding when code deviates for valid (undocumented) reasons

Real World Outcome

A CI/CD step that fails if the code deviates from the architectural “source of truth.”

Example Output:

$ drift-check --adr-dir ./adrs --code-dir ./src
Checking ADR #005: "Use Redis for Session Storage"...
Found in code: express-session using 'MemoryStore'.
[FAIL] Architectural Drift detected! Code does not match ADR #005.

Project 7: The Pre-Mortem Simulator (Failure Analysis)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: JavaScript (React/Vue)
  • Alternative Programming Languages: Python (Flask)
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 1. Resume Gold
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Risk Management / User Experience
  • Software or Tool: Scenario Generation
  • Main Book: “Noise” by Daniel Kahneman

What you’ll build: An interactive “War Room” simulator. You input a decision (e.g., “Moving to Microservices”). The tool then presents “Future Failure Scenarios” (e.g., “It is one year from now and the microservices have caused a total system outage. What happened?”) and forces the user to write down “Preventative Hygiene” for each.

Why it teaches Decision Hygiene: It teaches the Pre-Mortem technique. By imagining failure before it happens, you identify hidden assumptions and risks that your ADR should have addressed.

Project 9: The “Why” Chain Linker (Root Cause Decisions)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Python
  • Alternative Programming Languages: JavaScript, Go
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 1. Resume Gold
  • Difficulty: Level 1: Beginner
  • Knowledge Area: Logical Reasoning / Documentation
  • Software or Tool: Markdown, Graphviz
  • Main Book: “The Toyota Way” by Jeffrey Liker

What you’ll build: A tool that forces a “5 Whys” analysis for every ADR. Before an ADR can be finalized, the user must answer “Why?” five times to reach the business or technical root cause. The tool then links these levels into a visual chain.

Why it teaches Decision Hygiene: It prevents “Surface Decisions.” You learn that “We need a cache” isn’t a decision; “The database latency is too high because we have redundant join queries caused by our current schema” is the context that leads to the decision.

Core challenges you’ll face:

  • Prompt Engineering → maps to Guiding the user to deeper answers
  • Relationship Mapping → maps to Connecting ‘Why 1’ to ‘Why 2’
  • Context Injection → maps to Merging the 5 Whys into the ADR template

Project 10: The RFC Gatekeeper (Peer Review Workflow)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Go
  • Alternative Programming Languages: Node.js, Python
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 4. Open Core Infrastructure
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Workflow Automation / Git Internals
  • Software or Tool: GitHub/GitLab Webhooks
  • Main Book: “Code Complete” by Steve McConnell

What you’ll build: A bot that manages the RFC (Request for Comments) process. It ensures that an architectural proposal stays in the “Draft” state until a minimum number of diverse stakeholders (e.g., one Security, one DevOps, one Product) have provided feedback.

Why it teaches Decision Hygiene: It teaches the Review Hygiene. You learn that decisions made in a vacuum are fragile. By forcing cross-functional review, you catch the “Security holes” or “Product misalignments” before the code is written.

Project 11: The Conflict Resolution Ledger (Documenting Disagreement)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Python
  • Alternative Programming Languages: Ruby, TypeScript
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 3. Service & Support
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Dispute Resolution / Social Engineering
  • Software or Tool: SQLite
  • Main Book: “Crucial Conversations” by Patterson, Grenny, et al.

What you’ll build: A specialized ADR extension that explicitly documents “Alternative Options Considered” and “Why they were rejected.” It should include a “Minority Report” section for dissenting opinions.

Why it teaches Decision Hygiene: It addresses “Consensus Bias.” You learn that a strong architecture is one that survived strong arguments. Documenting why you didn’t pick Option B is often more important for future developers than why you picked Option A.

Project 13: The Expiration Tracker (Decision Retirement)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Python
  • Alternative Programming Languages: JavaScript, Go
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 2. Micro-SaaS
  • Difficulty: Level 1: Beginner
  • Knowledge Area: Lifecycle Management
  • Software or Tool: Cron, Email/Slack APIs
  • Main Book: “Building Evolutionary Architectures” by Neal Ford

What you’ll build: A system that attaches an “Expiration Date” or “Review Date” to every ADR. When the date arrives, the tool notifies the current owner to “Re-validate,” “Supersede,” or “Retire” the decision.

Why it teaches Decision Hygiene: It challenges the “Decisions are Forever” myth. You learn that a decision made for a 10-person startup is likely wrong for a 100-person scale. Hygiene requires regular pruning of old choices.

Project 14: The Weighted Consensus Engine (Committee Disrupter)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: Go
  • Alternative Programming Languages: Rust, Python
  • Coolness Level: Level 4: Hardcore Tech Flex
  • Business Potential: 5. Industry Disruptor
  • Difficulty: Level 4: Expert
  • Knowledge Area: Game Theory / Voting Systems
  • Software or Tool: Quadratic Voting logic
  • Main Book: “Radical Markets” by Eric Posner & Glen Weyl

What you’ll build: A tool for technical committees to vote on proposals. Instead of “one person, one vote,” it uses “Quadratic Voting” or weighted tokens based on “Domain Expertise” (e.g., a Security expert’s vote counts more on an Auth ADR).

Why it teaches Decision Hygiene: It exposes the politics of architecture. You learn that expertise should be weighted, but consensus still requires buy-in. It forces you to model how “Consulted” (from RACI) actually impacts the final “Accountable” choice.

Project 15: The Context Explorer (Knowledge Graph)

  • File: DECISION_HYGIENE_AND_ARCHITECTURE_MASTERY.md
  • Main Programming Language: JavaScript (React + Three.js or Cytoscape)
  • Alternative Programming Languages: Python (Neo4j)
  • Coolness Level: Level 5: Pure Magic
  • Business Potential: 4. Open Core Infrastructure
  • Difficulty: Level 5: Master
  • Knowledge Area: Graph Theory / Knowledge Management
  • Software or Tool: Neo4j / GraphQL
  • Main Book: “Fundamentals of Software Architecture” by Mark Richards

What you’ll build: A 3D or interactive 2D graph that visualizes the entire history of your architecture. Nodes are ADRs, edges are “Supersedes,” “Depends on,” or “Conflicts with.” Users can “time-travel” to see how the architecture looked two years ago.

Why it teaches Decision Hygiene: It is the ultimate visualizer of the “Random Walk” vs. “Strategy.” You see the clusters of decisions and the “dead ends” where bad choices were walk-backed.

Project Comparison Table

Project Difficulty Time Depth of Understanding Fun Factor
1. ADR Sentinel Level 1 Weekend High (Foundations) ★★★☆☆
2. Reversibility Score Level 2 1 week Very High (Risk) ★★★★☆
4. Assumption Auditor Level 3 2 weeks Extreme (Systems) ★★★★★
6. Drift Detector Level 3 2 weeks High (Practicality) ★★★★☆
8. Debt Calculator Level 3 2 weeks High (Financial) ★★★☆☆
14. Consensus Engine Level 4 1 month High (Political) ★★★★☆
15. Context Explorer Level 5 1 month+ Extreme (Visual) ★★★★★

Recommendation

If you are a solo developer: Start with Project 1 (ADR Sentinel). It will immediately improve how you track your own personal projects and build the habit of “writing it down.”

If you are a team lead: Start with Project 2 (Reversibility Scorecard) and Project 5 (RACI Oracle). These solve the most common team friction points: “Who decides?” and “Why are we spending so much time on this?”

Final Overall Project: The Architectural Flight Recorder

What you’ll build: A comprehensive platform that integrates the ADR Sentinel, the Assumption Auditor, and the Drift Detector. It acts as a “Black Box” for your software project. It records every decision, tracks the health of its assumptions in real-time by monitoring code/telemetry, and alerts the team when a decision is no longer valid.

Why it teaches Decision Hygiene: This is the culmination of all concepts. It moves architecture from a “static document” to a “living system.” You will understand that Decision Hygiene is not a one-time task, but a continuous loop of:

  1. Decision (Accountable owner + context)
  2. Monitor (Assumption health + drift)
  3. Review (Timeboxes + expiration)
  4. Iterate (Superseding old choices)

Summary

This learning path covers Decision Hygiene through 15 hands-on projects. Here’s the complete list:

# Project Name Main Language Difficulty Time Estimate
1 ADR Sentinel Go Level 1 Weekend
2 Reversibility Scorecard Python Level 2 1 week
3 Spike Timeboxer JavaScript Level 2 1 week
4 Assumption Auditor Python Level 3 2 weeks
5 RACI Oracle TypeScript Level 1 Weekend
6 Drift Detector Python Level 3 2 weeks
7 Pre-Mortem Simulator JavaScript Level 2 1 week
8 Debt Interest Calculator Python Level 3 2 weeks
9 “Why” Chain Linker Python Level 1 Weekend
10 RFC Gatekeeper Go Level 2 1 week
11 Conflict Resolution Ledger Python Level 2 1 week
12 Architecture Dashboard JavaScript Level 3 2 weeks
13 Expiration Tracker Python Level 1 Weekend
14 Consensus Engine Go Level 4 1 month
15 Context Explorer JavaScript Level 5 1 month+

For beginners: Start with projects #1, #5, #9, and #13. For intermediate: Jump to projects #2, #3, #7, and #10. For advanced: Focus on projects #4, #6, #8, #14, and #15.

Expected Outcomes

After completing these projects, you will:

  • Stop treating every decision as equally important.
  • Be able to walk into a messy codebase and reconstruct the why using forensic techniques.
  • Prevent “Death by Committee” by enforcing clear ownership.
  • Build architectures that are resilient to people leaving the team.
  • Quantify technical risk in a way that businesses can actually understand.

You’ll have built 15 working projects that demonstrate deep understanding of Decision Hygiene from first principles.

Thinking Exercise

The Root Cause Dive

Scenario: “We are switching from REST to GraphQL.” Why 1: Because the frontend is making too many requests. Why 2: Because the REST endpoints are too granular. Why 3: Because our data model is highly relational and the UI needs deeply nested data. Why 4: Because we designed our API around our DB tables, not our UI needs. Why 5: Because we didn’t have a UX Designer when we built the first version.

Question: Does GraphQL actually solve “Why 5”? If not, what decision actually addresses the root cause?

The Interview Questions They’ll Ask

  1. “How do you quantify the risk of an architectural choice to non-technical stakeholders?”
  2. “What is ‘Architectural Drift’ and how do you prevent it in a fast-moving team?”
  3. “Explain the ‘Pre-Mortem’ exercise. When should you use it?”
  4. “How do you distinguish between ‘Strategic Technical Debt’ and ‘Reckless Technical Debt’?”