Decay and Sustainability

Core Concepts

Rationale Decay

Most documentation degrades. This is not a failure of discipline — it is a structural property of how systems and organizations change. The problem has a name: rationale decay, the gradual loss of completeness and accuracy in recorded design decisions as systems evolve without corresponding updates to the documentation that describes them.

The research is direct on the economics: complete design rationale is too costly to maintain systematically. In practice, organizations limit formal rationale documentation to only the most critical decisions. Everything else lives in people's heads, in Slack threads, in the memory of whoever was in the room — and decays accordingly.

Decay compounds through two distinct channels. The first is organizational memory fade — knowledge that walks out the door when people leave. The second is systematic staleness — documented knowledge becoming structurally obsolete as the system it describes evolves. These are separate problems with partially different solutions.

Polanyi's Limit: What Cannot Be Written Down

There is a deeper problem beneath documentation maintenance. Some knowledge cannot be fully encoded, regardless of how much effort is invested.

The philosopher Michael Polanyi identified this limit in a principle that has become foundational to knowledge management: "We can know more than we can tell." His argument is not merely practical but logical: a wholly explicit knowledge is logically unthinkable. Explicitly rendered knowledge always depends on tacit understanding to be applied. All knowledge is either tacit or rooted in tacit knowledge — the two are fundamentally interdependent, not separable.

"The tacit-explicit gap is not a problem to be solved through better documentation tools, but rather a permanent feature of how human knowledge functions."

For engineering teams, this means design rationale that depends entirely on documentation inherently cannot capture the full complexity of architectural decisions. The senior engineer who holds fifteen years of context about why the event queue is structured the way it is — the constraints that were attempted and failed, the organizational pressures that shaped the final design — cannot fully transmit that understanding by writing it down. The documentation can carry explicit structure. The judgment that informs how to extend it correctly cannot be transferred through text alone.

The SECI Model: Why Documentation Is Only One Stage

Nonaka and Takeuchi's SECI model offers a more complete picture of how knowledge moves through organizations. The model defines four conversion modes that organizations cycle through to create and preserve knowledge:

Fig 1

The critical insight from the SECI model is that rationale decay occurs when knowledge becomes stuck in any single stage, loses continuity moving between stages, or reverts when organizational structures change. Most engineering teams invest almost entirely in Externalization — writing things down. They underinvest in Socialization (which cannot be replaced by tools) and rarely design for Internalization (how engineers absorb and apply what is written).

Socialization Cannot Be Shortcut

Of the four SECI modes, Socialization is the one organizations most readily sacrifice. It requires time, physical or sustained virtual proximity, trust, and continuity of relationship. Socialization cannot be accelerated through documentation or tools; it requires sustained interpersonal contact and time.

When experienced practitioners leave, the socialization pathways that preserve implicit design understanding are severed. The documentation left behind cannot substitute for the knowledge that lived in mentoring relationships and shared practice. Rationale decay is fundamentally a crisis of disrupted socialization — a breakdown of human knowledge transmission networks that documentation tools can supplement but cannot replace.

The Structural Barriers to Codification

Even when teams are willing and have time, codifying tacit knowledge faces structural obstacles. Research estimates that approximately 90% of an organization's knowledge exists embedded in employees' minds — not only difficult to articulate but difficult even to identify. Employees execute processes habitually without conscious awareness, making the knowledge invisible to both the knower and potential documenters.

The barriers cluster into five types:

Barrier	Description
Perception gap	Not knowing what you know that others don't
Language limitation	Difficulty expressing embodied or contextual knowledge
Temporal constraint	No time to articulate during active work
Value misalignment	Perceiving knowledge sharing as losing competitive advantage
Spatial distance	Reduced informal transfer in distributed or remote teams

This taxonomy matters because each barrier points to a different intervention. Perception gaps require structured reflection (postmortems, pre-mortems). Language limitations require collaborative articulation (pair documentation, interview-based knowledge capture). Temporal constraints require slack capacity in team planning. Value misalignment requires cultural and incentive change. Spatial distance requires deliberate investment in informal channels across distance.

Knowledge Loss Through Turnover

Employee departure is the most acute knowledge loss event. When employees leave, they take with them irreplaceable tacit knowledge — the unarticulated understanding of why systems work the way they do. The research defines organizational knowledge loss as "intentional or unintentional evaporation of knowledge that accumulates from learning and from individual and collective actions."

Departure of key personnel disrupts three interdependent things simultaneously: relational knowledge networks (who knows what and who to ask), availability of mentors for transfer, and organizational memory capacity for existing architectural decisions. The knowledge loss cascade affects not only productivity and efficiency but also system quality and organizational understanding of existing architectures.

Conway's Law and the Geography of Lost Knowledge

Conway's Law — that organizations design systems mirroring their communication structures — has a corollary for rationale preservation: as organizations restructure, the communication pathways that encode and transmit design rationale shift correspondingly.

When informal communication channels break down through geographic distribution, team reorganization, or ownership transfers, the tacit knowledge that flows through those channels becomes invisible. Teams separated across time zones face exaggerated coordination problems and loss of informal "quick questions" that preserve institutional understanding. Rationale encoded implicitly in team structure can be disrupted by organizational changes that alter communication bandwidth, creating blind spots where design knowledge becomes inaccessible despite the code remaining unchanged.

The inverse also matters: when using Conway's Law proactively (sometimes called the "inverse Conway maneuver"), team structure decisions should account for knowledge preservation, not just system boundaries. Who will remember why this seam exists in five years?

Institutional Memory at Organizational Scale

Rationale decay is not only a technical problem — it is a generational one. Institutional memory is destroyed through excessive downsizing, layoffs, and unmanaged transitions. The departure of experienced cohorts creates acute knowledge gaps that cannot be quickly replaced, regardless of hiring quality.

Effective preservation requires what the research calls knowledge cascades: specialists transmit understanding to cohorts who then teach the next level — a deliberate "pay it forward" model embedded in organizational processes. Organizations that successfully preserve institutional knowledge do so through intentional, ongoing commitment to knowledge management and cultural practices — not through documentation alone, but through continuous human-to-human transmission embedded in organizational structures.

---

Common Misconceptions

"If we write it down, it's preserved." Documentation preserves the explicit surface of a decision — the what and the stated why. It does not preserve the tacit judgment that makes that rationale legible and applicable to future situations. Polanyi's limit is not an engineering problem; it is a philosophical one. Better tooling does not resolve it.

"The real problem is that teams don't document enough." The software engineering community has experimented for over twenty years with rationale management approaches — IBIS, QOC, DRL, PHI — without any single approach achieving widespread adoption. The failure is not a discipline failure. It reflects a real economic and cognitive burden: complete design rationale is too costly to maintain. The answer is not more documentation, but smarter selection of what to document and active investment in the socialization practices that documentation cannot replace.

"Remote teams can compensate with better async documentation." Documentation can carry more explicit load in distributed teams — and should. But spatial distance exacerbates tacit knowledge sharing barriers. Informal "quick questions" that preserve architectural understanding do not happen naturally across time zones. Distributed teams that do not deliberately design for socialization — structured pairing, cross-timezone overlap time, explicit mentoring programs — will experience accelerated rationale decay, not mitigated decay.

"Rationale decay is a documentation maintenance problem." It is that, but it is more fundamentally a socialization maintenance problem. Documentation decays when no one updates it. Tacit understanding decays when the social structures that transmit it — mentoring relationships, shared context, team continuity — are disrupted. The latter is harder to measure and easier to overlook until it is too late.

---

Annotated Case Study

A Platform Team Reorganization

A platform team at a mid-sized technology company built and maintained a complex data ingestion pipeline over four years. The pipeline's architecture had several non-obvious properties: a deliberately sequential fan-out pattern chosen over parallel processing after a series of data consistency failures; a rate-limiting layer that had been tuned through months of production incidents; and a set of compensating transactions that existed because a third-party API used by the pipeline lacked idempotency guarantees.

None of this was documented. The choices were understood by the three engineers who had been present for the incidents that necessitated them. Two of them left within six months of each other. A company restructuring then moved the third to a different product team.

When a new engineering team took ownership of the pipeline, they saw an over-engineered system. The sequential fan-out looked like a missed optimization opportunity. The rate-limiting layer looked like dead code. The compensating transactions looked like unnecessary complexity.

Annotation — SECI failure: The team had done almost no Externalization. The rationale for the pipeline's structure existed only as Socialization — shared understanding between the original engineers. When the social structure was disrupted (through turnover and reorganization), the knowledge evaporated. There was no second-order transmission: no one had been onboarded into the team in a way that transferred the context.

Annotation — Conway's Law: The pipeline sat at a team boundary created by the reorganization. The new team had no communication pathway to the original authors. The informal channel that would have allowed a "quick question" about the rate-limiting layer — the kind of question that reveals institutional memory — did not exist. The knowledge was inaccessible despite being, in principle, recoverable if the original engineers had been reachable.

Annotation — What happened: The new team refactored the sequential fan-out to parallel processing. Within three weeks, they hit the same data consistency failures the original team had encountered four years earlier. The rate-limiting layer was removed as part of the refactor. The third-party API then caused cascading failures that took two weekends to diagnose. The compensating transactions were the last thing removed — a postmortem finally connected an engineer with the original architect, who explained the idempotency issue.

Annotation — The cost: Six months of rework. Three production incidents. The original decisions were the right ones. The rationale for them simply had not survived the organizational change. This is not a story about bad engineers; it is a story about a knowledge loss cascade triggered by turnover and restructuring.

Annotation — What a sustainable practice would have looked like: The original team needed both Externalization (incident-driven ADRs for the consistency failures; explicit documentation of the idempotency workaround) and deliberate Socialization investment during ownership transfer. The handover should have included structured sessions where the original engineers explained, not just wrote, the reasoning. Conway's Law could have been used proactively: when the restructuring was planned, the design rationale most at risk — everything living at the new team boundary — should have been identified and explicitly transferred.

---

Key Principles

1. Documentation is externalization, not preservation. Writing down a decision converts tacit knowledge to explicit knowledge. It does not preserve the judgment, context, and interpretive skill needed to apply that knowledge correctly. Treat documentation as one stage in a knowledge cycle, not the endpoint.

2. Design for knowledge transfer during organizational change. Reorganizations, team splits, ownership transfers, and geographic expansion all alter communication pathways and therefore alter which rationale is at risk. Before restructuring, map which design decisions live at the boundaries that will change. Plan explicit handoffs.

3. Socialization requires investment, not just intention. Mentoring, pairing, deliberate overlap time, structured onboarding, and cross-team working sessions are not soft concerns — they are the primary mechanism for preserving tacit knowledge. They require time, trust, and continuity. Budget for them explicitly.

4. Turnover planning is rationale risk management. When a key practitioner is leaving, identify what they hold that is not elsewhere in the team's knowledge system. Run targeted knowledge transfer sessions before they leave, not after. Knowledge loss cascades are harder to reverse than to prevent.

5. Conway's Law predicts where your blind spots will form. The modules and systems that sit at team boundaries, or that changed ownership in a restructuring, are the highest-risk zones for rationale decay. These are the places to audit documentation quality and active knowledge transfer, not the core systems that have stable ownership.

6. Select what to document based on decay rate, not importance. Not everything can be fully documented. Prioritize decisions where the rationale is most at risk of decay: decisions made under constraint (the constraint may change), decisions that encode non-obvious tradeoffs, and decisions whose rationale lives in a single person or former team.

---

Thought Experiment

Your organization is planning a major restructuring: a large platform team will be split into three smaller product-aligned teams. The restructuring makes organizational sense. You are asked to sign off on it from a technical architecture perspective.

Before you respond, consider:

The platform team has been operating for five years. They own a set of shared infrastructure components whose design reflects years of accumulated incident response, performance optimization decisions, and API compatibility constraints negotiated with dependent teams. None of the engineers who made the earliest decisions are still at the company. The current team has absorbed this knowledge through a combination of documentation (partial and uneven), tribal knowledge passed down through tenure overlap, and informal institutional memory that lives in Slack threads and individual recall.

The restructuring will split this team along product lines. Each new team will own the infrastructure components their product depends on. The three new teams will have different managers, different planning cycles, and be located in different offices.

Questions to sit with:

1. Which design decisions in the shared infrastructure are most at risk under the new structure? How would you identify them before the split happens?

2. Conway's Law predicts the new team structure will eventually be reflected in the architecture of the systems they own. What does this suggest about which components should be seamed differently before the split?

3. The reorganization is happening over a six-week transition period. What would a knowledge preservation plan look like for that window? What is achievable in six weeks, and what is not?

4. After the restructuring is complete, what organizational mechanisms would you recommend to maintain cross-team knowledge flow for the infrastructure that is now distributed across three teams? What does the SECI model tell you about which mechanisms are most important?

5. Three years from now, a new engineer joins one of the three teams and reads the documentation left from before the split. What will they be able to reconstruct from the documentation? What will they have no way to know?

There is no single right answer. The value of this exercise is in making explicit which knowledge is most at risk and why — before the decay begins.