Design Document Staleness

A design document accurately described the architecture when written, then stopped tracking the code; the reader has no way to tell.

A contributor opens docs/security/sandbox.md from a Gerrit comment dated 2019, follows the diagram, writes a Mojo interface around the trust boundaries the document names, and sends the change for review. The change is rejected on grounds the document never mentions. The document still describes the 2019 architecture accurately. It no longer describes the current architecture accurately. The page does not say which claims survived, and project tooling does not warn on the way in. The contributor was not wrong to trust a document linked from review; the document is wrong to remain unmarked.

Symptoms

• A docs/ page reads as authoritative and dates itself either not at all or only by Git history.
• The page describes a class layout, interface boundary, or process model that does not match the source tree at the current commit. A senior contributor sees the discrepancy on a quick read; a new contributor reading carefully does not.
• A code-review comment ends with “see docs/<file>.md” and a senior reviewer responds with “that doc is from 2019; ignore section 4.”
• An AI coding agent generates code consistent with the document and inconsistent with the architecture. The agent reproduced the document faithfully; the document was the wrong source.
• A design document references a class, file, or directory that has been renamed or removed. The link still works because mdbook-linkcheck verifies that the target page exists, not that the cited symbol still lives there.
• A diagram in a document shows components whose names match the source tree but whose connections do not; the components were preserved through the refactor and the connections were not.
• An RFC-style discussion thread on blink-dev referenced for the rationale of a 2017 decision has been superseded by a 2023 follow-up thread, and the document points only at the earlier one.

Why It Happens

Chromium has no policy requiring design-document updates when architecture changes. No commit-blocking check flags a CL that touches a file referenced in docs/. No scheduled audit samples documents against the code they describe. The drift is structural: the code is under continuous review and continuous test, while many documents are under neither.

The incentives point away from keeping the documents current. An engineer landing an architectural refactor is judged on whether the code is correct, the tests pass, and the API owners and OWNERS reviewers cleared it. The review process does not grade whether documents describing the predecessor still match. The post-refactor documentation update becomes a discretionary follow-up CL. It competes with the next prioritized change, and it loses. Sometimes the original document’s author has left the team or the project; the people with the context to update it are not the people who shipped the refactor.

The two-level review structure compounds the problem. Code is reviewed at the change boundary, by people who have the context to evaluate it. Documents are reviewed at the document boundary, by people who may not have the context to evaluate either the old text or the proposed replacement. An OWNERS member who notices that section 4 of docs/<file>.md is stale faces a higher cost to fix it than to live with it. A corrective CL means reading the section carefully, tracing the current behavior in the source tree, writing an accurate replacement, and getting it past whatever OWNERS the doc happens to be under. Living with the staleness means saying so out loud to the next contributor who cites the section in review.

Chromium’s organizational shape adds another pressure. A document owned by a sub-team that has moved on stays stale because no other sub-team has standing or context to update it (see Conway’s Law in Multi-Org Chromium). Ownership is distributed across Google, Microsoft Edge, Igalia, Intel, Samsung, and others. The document author and the current code’s effective owner are often not the same population, and they may share no review surface.

The Harm

Three populations absorb the cost.

New contributors waste days following diagrams that no longer match the code. The wasted days are doubly costly. The contributor fails to make progress on the actual change and acquires a false model of the architecture. That model then propagates through later review comments and through conversations with the next cohort of new contributors.

Downstream-vendor engineers (Microsoft Edge, Brave, Vivaldi, Opera, Samsung Internet, Electron and WebView2 integrators, enterprise-fork operators) read the documents from outside the project and have no senior-contributor sanity check on their way in. A Brave engineer who reads a 2020 architectural document describing a process model that was substantially revised in 2023 may build downstream logic against the stale model and discover the divergence only when an upstream change breaks their assumption.

AI coding agents trained on the public corpus reproduce stale documents at full fluency. The agent’s training data does not carry a “last verified” date or a cross-check against the current source tree. An agent that has internalized a stale design document can generate architecturally invalid code with the same confidence it brings to current architecture. The agent has no way to know the difference. Downstream consumers of the output (downstream-vendor engineers, enterprise contributors, the agent’s user) inherit the document’s staleness through the agent. They pay the same cost the original document’s reader would have paid, with the added cost that the agent’s authority has erased the document’s date.

A fourth cost is the erosion of trust in the formal record. When a senior reviewer routinely qualifies a docs/ citation with “ignore section 4,” the implicit lesson is that the formal record is not authoritative without senior intermediation. The project’s nominal commitment to “formal decisions in formal channels” (see Formal-Informal Channel Split) holds nominally and fails in practice. The operative knowledge migrates further into Tribal Knowledge, the substrate downstream consumers and new contributors have the least access to.

The Way Out

There is no project-level fix shipping; the structural conditions that produce the antipattern are still in place. The mitigations available to readers and downstream consumers operate at the citation level, not at the project level.

Read every docs/ page as evidence dated by Git history, not as a current description. Open the file’s Git log on Gitiles before trusting an architectural claim from it. A document last touched in 2019 describes the architecture as of 2019 and is presumptively stale on any claim about a system actively developed since. The presumption can be falsified; a document describing a stable architectural primitive may still be current. The burden of falsification rests on the reader.

Cross-check architectural claims against the source tree at the commit being changed. A document that names a class RenderProcessHostImpl and a method RenderProcessHostImpl::CreateChannel() is checkable. Open content/browser/renderer_host/render_process_host_impl.cc at the working commit and confirm the method exists and does what the document says it does. The check is fast for any specific claim and expensive only in aggregate; do it for the claims the change depends on.

When citing a docs/ page in a code-review comment, design document, or written-down rationale, cite the commit SHA at which the document was current to the reading. A citation like “docs/security/mojo.md as of 7b8e2c4” survives later staleness in a way a citation to main does not. The discipline scales: every architectural reference in any persistent record (design document, runbook, agent grounding context, security review) gains durability from a pinned SHA and loses durability without one.

When an AI coding agent’s grounding context includes a docs/ page, qualify the inclusion with the document’s date and the date of last verification against the source tree. An agent reading a document dated 2019 with no verification handle has no signal that the document might be stale. An agent reading the same document with last_verified: 2026-05-13, possibly stale on V8 heap layout post-2024 sandbox transition has a signal that scopes the document’s authority to claims unaffected by the named transition.

When a CL substantively changes an architectural surface that a docs/ page describes, file a follow-up CL that either updates the page or marks it stale on the affected sections. The cost is small at the moment of the original CL and large in aggregate over the lifetime of the document. Treat the follow-up as part of the change, not an optional courtesy.

How It Plays Out

A new contributor at a downstream-vendor enterprise-browser team reads docs/security/sandbox.md to understand the OS sandbox model. Section 4 describes the renderer sandbox as relying on a particular set of seccomp-bpf filters that were materially revised after the 2022 ipcz transport landed. The contributor builds a downstream patch against the section-4 model. The upstream sandbox no longer applies those filters in the same configuration, and the patch diverges from upstream behavior. Diagnosis takes three days and one senior-engineer Slack DM. The senior engineer’s reply ends “yeah, that doc has been wrong since ipcz.”

Inside a Cursor-equivalent harness, an AI coding agent produces a Mojo interface for a new feature. It generated the interface against a 2020 design document that described stateful initialization as acceptable for low-frequency setup operations. The current convention (see Stateful IPC Initialization) treats stateful initialization as an antipattern regardless of frequency. The output passes static analysis and fails the human security review. The failure is illegible to the agent’s user because the user trusted the agent’s output and the agent trusted the 2020 document. Recovery costs the same diagnostic time a senior reviewer would have spent on a new human contributor’s mistake, with one added dimension: the user lacks the senior reviewer’s context. The diagnosis runs through the agent’s full output rather than through the document’s named sections.

A 2017 design document for the V8 garbage collector survives a 2024 architectural refactor unchanged. A new V8 contributor cites the document in a CL description. The API owner reviewing the CL responds with “section 6 is current; sections 1 through 5 describe the predecessor and have not been corrected.” The contributor’s CL lands; the document remains. Eighteen months later, a different new contributor cites the same document and gets the same response from a different reviewer. The conversion path from tribal knowledge to formal record is open in principle and closed in practice for this document. The cost of fixing it has stayed higher than the cost of saying so once per encounter.

Notes for Agent Context

When an architectural claim comes from a Chromium docs/ page, treat the page as dated evidence rather than current truth. Open the file’s Git log on Gitiles and read the date of the last substantive change. Treat any claim about a system actively developed since that date as presumptively stale until it is cross-checked against the source tree at the working commit.

Before generating Chromium-architecture code based on a docs/ page, name the document’s last-substantive-update date and the surfaces whose later evolution may have invalidated the relevant claims: process model, IPC transport, V8 sandbox, sandbox policy, or SiteInstance identity. Request explicit human verification before generating code that depends on the claim.

Do not treat the absence of a “deprecated” or “superseded” marker on a docs/ page as a guarantee that the page is current. Chromium has no policy requiring such markers when architecture changes, so their absence is uninformative.

When citing a docs/ page in code comments, CL descriptions, or written-down rationale, cite the commit SHA at which the document was current to the reading, not the document’s main-branch URL.

Related Patterns

Sources

The intellectual lineage of the documentation-rot phenomenon belongs to the broader software-engineering literature. David Lorge Parnas’s 1986 paper A Rational Design Process: How and Why to Fake It (with Paul Clements) names the gap between the orderly design record the field tells itself it produces and the messier record it actually maintains. The paper’s prescriptive proposal (to fake the rational record after the fact for the benefit of subsequent readers) is one of the literature’s earliest acknowledgments that design documentation, left to drift, will not match the system it describes. Timothy Lethbridge, Janice Singer, and Andrew Forward’s 2003 IEEE Software paper How Software Engineers Use Documentation: The State of the Practice reports survey findings on documentation rot and reader workarounds in industrial practice. The Chromium-specific evidence is distributed across the project’s docs/ directory itself (the antipattern is in evidence in the directory it lives in) and the blink-dev archive (where reviewers routinely qualify docs/ citations in thread responses). The Linux Foundation’s January 2025 announcement of the Supporters of Chromium-Based Browsers initiative frames cross-organization knowledge-record maintenance as an ecosystem-level problem worth funding, which is a partial structural acknowledgment of the conditions this antipattern names.

Technical Drill-Down

• docs/ directory on Gitiles — the body of evidence; open any file’s history (Log link at the top right of a Gitiles page) to read it as dated rather than current.
• docs/security/sandbox.md — a canonical instance where post-ipcz updates have not fully propagated; read with the Git log open.
• docs/security/mojo.md — a counter-example: actively maintained as IPC conventions have evolved, illustrating the conversion path the antipattern obstructs in the general case.
• blink-dev archive — where reviewers routinely qualify docs/ citations in thread responses; one of the project’s main signals that a given document is stale.
• Parnas and Clements, A Rational Design Process: How and Why to Fake It (1986) — foundational treatment of the gap between idealized and actual design records.
• Lethbridge, Singer, Forward, How Software Engineers Use Documentation (2003) — empirical survey of documentation rot in industrial practice.
• Linux Foundation: Supporters of Chromium-Based Browsers (January 2025) — ecosystem-level recognition of the cross-organization documentation-maintenance problem.