Your architecture decisions are dying. Not with a dramatic crash or a fiery post-mortem, but through slow, silent decay. While your code sits safely in version control, every line change tracked, reviewed, and reversible, the rationale behind your system’s design evaporates into the ether of Slack threads and hallway conversations.
This isn’t a new problem, but it’s reaching a crisis point. A recent discussion on software architecture forums crystallized what many of us have felt: we version code, we review code, we roll back code, but decisions disappear. A developer named Humble-Plastic-5285 coined the term “Decision-Centric Development” not as a shiny new methodology, but as a name for the missing layer of memory teams desperately need but don’t have.
The Memory Gap: Where Decisions Go to Die
Six months after a major deployment, nobody remembers why you chose that database, why you broke the monolith at those specific seams, or why you accepted that technical debt. The metrics moved, incidents happened, but the original decision context is gone. You’re left with a system that makes no sense to the people currently maintaining it.
One commenter captured the essence perfectly: “preserving decision context is the exact purpose of ADRs. to record why a choice was made, the constraints at that time, the trade offs accepted, and to give future teams the context code alone can’t carry.”
But here’s the rub: most teams are already writing ADRs, and they’re still losing the war on knowledge decay.
The ADR Band-Aid Problem
Architecture Decision Records were supposed to be the solution. Document the “why” in a markdown file, commit it alongside your code, and voilà, instant context preservation. In practice, it’s more complicated.
A tech lead with years of ADR experience shared their reality: “In theory, it feels like the two types of documentation should fit together seamlessly. The tech design document is intended to capture the proposed implementation… ADRs should be some of those later docs. In practice, these fit together in a clunky way. I think part of it is that we don’t really revisit ADRs or tech designs later on to consider how things turned out.”
The pattern is depressingly consistent:
– Write the ADR (capture intent at a point in time)
– Implement the decision
– Never look at the ADR again
– Lose the people who were there
– Lose the context forever
Another engineer pointed out the hardest part isn’t writing decisions, it’s “reconnecting them with what actually happened months later especially when people move on.” When you’re the only person left from a 15-person project a year later, who evaluates whether that microservices split was actually worth it?
The Tribal Knowledge Trap
The most insidious form of decision loss happens when knowledge becomes people-dependent. One developer described their daily reality: “I find myself repeating these as context in every communication channel if it appears that people have forgotten them: meeting, email, slack… When decision context only lives in repeated explanations across meetings, Slack, and emails, it becomes a people dependent system.”
This works until it doesn’t. The moment the right person is absent, overloaded, or leaves for a better opportunity, the system breaks. The problem isn’t communication skill, it’s that your system has no durable memory.
Performance reviews make this worse. This constant context-repetition requires significant cognitive overhead, yet “this is not something rewarded for in performance reviews (unless you’re the tech lead/manager/architect). Nor is it something tested for in leetcode/software design systems interviews.” We’re incentivizing speed over sustainability, and the bill comes due during the next outage.
The Feedback Loop Failure
The gap between decision and outcome is where most documentation strategies collapse. As one commenter noted, what’s often missing is “closing the loop: revisiting the decision with outcome data once reality hits.”
Think about it: When was the last time your team scheduled a “decision retrospective”? We have post-mortems for incidents, sprint retros for process, but decisions themselves, the atomic units of architectural evolution, go unevaluated.
A developer working at a “scale-up” described the churn problem: “there’s quite a bit of churn among EMs and PMs for a given team or project on top of normal departures. How do you get people to evaluate how a decision turned out when a year later you’re the only one from the 15 person project still working on that part of the codebase?”
Decision-Centric Development: A Better Approach
The core insight is that decisions aren’t static artifacts, they’re living hypotheses about the future that need continuous validation. Here’s what a functional decision-centric system looks like:
1. Decision as Code
Treat decisions like you treat infrastructure: versioned, testable, and observable. ADRs should be more than markdown files, they should be queryable databases linked to your observability stack. When that database choice causes latency spikes at 3 AM, your incident response dashboard should surface the original decision context automatically.
2. Close the Loop with Outcome Data
Every significant decision needs a follow-up mechanism. Schedule calendar reminders for 3, 6, and 12 months post-implementation. Ask:
– Did the decision solve the problem it was meant to solve?
– What new problems did it create?
– Given what we know now, would we make the same choice?
This isn’t about blame, it’s about organizational learning. The Rust community understands this implicitly, their RFC process requires extensive rationale documentation and often includes “future possibilities” sections that serve as built-in revisit triggers.
3. Make Decision Health Visible
Just as you monitor system health, monitor decision health. Create a dashboard showing:
– Decisions approaching their “review by” date
– Decisions made by team members who’ve since left
– Decisions tied to components with high incident rates
The New Stack’s article on agentic systems emphasizes making cost visible and actionable. Apply the same principle to decisions: if you can’t measure the impact of a choice, you can’t preserve its context.
4. Institutionalize Decision Reviews
Make decision retrospectives a first-class ceremony. When a senior engineer leaves, conduct “knowledge extraction” sessions focused on architectural decisions. Record these sessions. Transcribe them. Link them to the relevant code and documentation.
The Controversial Truth
Here’s what makes this topic genuinely spicy: most organizations don’t actually want to preserve decision context. They want to move fast, ship features, and avoid dwelling on past choices that might reveal mistakes or inefficiencies. Documenting decisions feels like overhead, evaluating them feels like admitting failure.“`