--- slug: tribal-knowledge type: concept summary: "The architectural constraints, historical rationale, and unwritten conventions senior Chromium contributors carry outside indexed records, available only by asking the right person." created: 2026-05-12 updated: 2026-05-22 last_link_verified: 2026-05-22 related: design-doc-staleness: relation: produced-by note: "Design Document Staleness is the antipattern that promotes formal-channel knowledge into the tribal layer: when the written record stops tracking the code, the operative knowledge stays in heads and informal channels by default." formal-informal-split: relation: substrate-of note: "The formal-informal channel split describes the communication ecosystem; tribal knowledge is what the informal half of that split carries between contributors." conways-law: relation: shapes note: "Conway's Law in Multi-Org Chromium determines whose tribal knowledge becomes load-bearing for which subsystem — the social distribution of the source tree decides whose heads hold the answer to which architectural question." owners-file-governance: relation: encodes note: "OWNERS file membership is the project's nearest-to-formal proxy for who carries the relevant tribal knowledge for a given directory; an OWNERS entry is the project's commitment that the named contributor's tacit context is current." intent-ship-pipeline: relation: depends-on note: "The Intent to Ship Pipeline's rigor depends on API owners carrying tribal knowledge about web-platform precedent that is not written anywhere a new contributor can read — what shapes of web API have failed in the past, what shapes have surprised the standards bodies, what reviewers' specific reservations recur." stateful-ipc-init: relation: incubates note: "Stateful IPC Initialization is a canonical example of an antipattern that lived as tribal knowledge for years (reviewers refused it on sight) before it was written down in `docs/security/mojo.md` — the failure mode the catalog is here to interrupt." untrusted-renderer-axiom: relation: incubates note: "The Untrusted Renderer Axiom existed as tribal knowledge in the security team's review reflexes long before it was canonicalized in `docs/security/rule-of-2.md`; the lag between the rule's operation and its documentation is what the concept names." --- # Tribal Knowledge *Architectural constraints, historical rationale, and unwritten conventions senior Chromium contributors carry outside indexed records.* > **Concept** > > Vocabulary that names a phenomenon. ## What It Is Tribal knowledge is operational knowledge the project needs but has not written down where a new reader can find it. In Chromium, it includes why a design proposal stalls at API-owner review, the reviewer reflex that catches a stateful Mojo interface, how Edge, Mozilla, and W3C readers interpret `blink-dev` shorthand, the 2018 Site Isolation precedents that shape Android process-consolidation tradeoffs, and the patch history a directory's OWNERS members carry in their heads. None of it is secret. Much of it has been said aloud in a Slack thread, a code-review comment, a conference talk, or a mentoring session. It is binding knowledge that remains available only by asking the right person. The term predates Chromium. Polanyi's distinction between explicit and tacit knowledge in *The Tacit Dimension* (1966) names the part of working competence practitioners possess but cannot fully articulate. Nonaka and Takeuchi's *The Knowledge-Creating Company* (1995) gave the organizational-learning literature its vocabulary for tacit-to-explicit conversion. Chromium adds a harder case: a seventeen-year-old, multi-organization, multi-language, security-critical codebase where tacit knowledge affects architecture, security review, standards work, and downstream-product risk. ## Why It Matters A reader who can name tribal knowledge can stop looking in the wrong place. Some Chromium questions have answers in `docs/` or the source tree. Others live in the review history, the people who were present for a decision, or the unwritten rule a senior reviewer applies on sight. Naming the phenomenon lets the reader route the question to the right population instead of treating missing documentation as missing reality. The stakes are highest for downstream-vendor engineers and AI coding agents. Microsoft Edge, Brave, Vivaldi, Opera, Samsung Internet, Electron-application teams, WebView2 integrators, and enterprise-fork operators make architectural decisions without having been present for the original reviews. AI coding agents trained on the public corpus reproduce explicit knowledge well and tacit knowledge poorly. An agent that writes a `mojom` interface with a `BeginSession`/`Report`/`EndSession` triplet is not merely making a bad style choice; it is reproducing a design shape no `docs/` page rules out and every senior security reviewer rejects on sight. ## How to Recognize It Tribal knowledge usually appears at the edge of an otherwise formal process. A `blink-dev` reviewer writes "we tried this in 2017 and it didn't work" without linking the original thread. An OWNERS member says "this isn't how we do it in this directory" without a citation. A Slack thread resolves an architectural dispute in three messages, then later design documents cite "the discussion in `#cr-platform-architecture` from March" as if that reference were durable. A conference talk names a rule, such as "never depend on `RenderProcessHost::FromID()` in a context where the renderer can be gone; there is no return value that means what you want it to mean." Everyone who heard the talk can apply the rule. Everyone else has to rediscover it. The clearer the sign, the closer the knowledge is to becoming explicit. The hardest cases do not announce themselves. A security reviewer rejects an IPC interface before they can compress the reason into a comment. A performance reviewer recognizes a main-thread starvation shape before any measurement exists. A content-layer reviewer sees that a refactor will fight `SiteInstance` identity propagation but cannot explain the whole history in the CL. These are the cases where conversion is expensive and non-conversion is more expensive. ## How It Plays Out An external contributor working at Igalia submits a `mojom` interface for a new feature with an `Init`/`Operate` pair. The reviewer replies, "let's keep this stateless; see `docs/security/mojo.md`." The document exists, the comment is precise, and the lookup is short. The contributor revises the interface and lands the change that week. This is the healthy conversion path: someone wrote the rule down, so the reviewer can cite it and the contributor can read it. A downstream enterprise-browser engineer asks why `RenderProcessHost::FromID()` returns the wrong process under a process-consolidation corner case. There is no `docs/` page for the answer. The OWNERS of `content/browser/renderer_host/` know the long history; the answer surfaces in a Slack DM, then a follow-up CL comment, then two retellings to other downstream-vendor engineers over the next quarter. No artifact survives the path. The knowledge remains operative and unindexed. An AI coding agent inside an enterprise browser vendor's harness produces a Mojo handler that reads a renderer-supplied `uint64_t` count and indexes into a fixed-size buffer without `base/numerics/safe_conversions.h`. The public corpus contains integer-semantics guidance, but the load-bearing rule is sharper: every renderer-supplied count, size, or offset is attacker-controlled and must be bounded against the message handler's actual buffer capacity, not trusted because a caller wrapped it. That rule existed in security-team review practice before it was documented and still appears more often in review comments than in one canonical page. The agent follows the written rule and misses the operative one. ## Consequences Naming tribal knowledge changes how a reader uses Chromium's records. `docs/` becomes the explicit subset of a larger body, not the whole body. A reader can ask whether a decision rests on verifiable written material or on tacit material held by named contributors, then route the question accordingly. [*Design Document Staleness*](design-doc-staleness.md) explains how formal-channel knowledge moves into the tribal layer. [*Formal-Informal Channel Split*](formal-informal-split.md) explains the substrate that carries it once it gets there. The cost appears in onboarding time and in unequal access. New contributors may spend six to twelve months moving from first CL to autonomous architectural judgment, much of it absorbing what is not written. Downstream vendors and AI-agent operators absorb the cost most directly because they have the least access to the people who carry the missing context. The Chromium project's investment in the `docs/` tree, Chrome University talks, the RenderingNG article series, and the Linux Foundation's Supporters of Chromium-Based Browsers fund (January 2025) is a partial structural response. None of these mechanisms eliminates the gap. ## Notes for Agent Context Never treat the absence of an explicit prohibition in Chromium `docs/` as permission. Binding constraints may live only in reviewer reflexes, historical context, or informal-channel precedent. If a proposed change touches IPC, sandboxing, process model, or `SiteInstance` identity, surface the tribal-knowledge precedents that might apply: rule-of-2 origins, Mojo-statelessness incidents, 2018 Site Isolation rollout constraints, or the renderer-process-can-be-gone identity-propagation rule. Flag the change for explicit human review before producing the CL. When citing a `docs/` page as justification, state the year the document was written and whether later reviewer practice may have superseded it. A document that has not been updated since 2019 is a candidate for [*Design Document Staleness*](design-doc-staleness.md). Do not paraphrase a Slack thread or hallway-conversation report as if it were an indexed primary source. It may be operative knowledge, but it is not citable in the form an AI-agent harness should treat as authoritative. ## Sources The intellectual lineage of the concept is Michael Polanyi's *The Tacit Dimension* (1966), which names the explicit/tacit distinction at the heart of working competence, and Ikujiro Nonaka and Hirotaka Takeuchi's *The Knowledge-Creating Company* (1995), which gave the organizational-learning literature its working vocabulary for tacit-to-explicit conversion. Chromium-specific evidence is distributed across the project's `docs/` tree (the explicit subset), the `blink-dev` archive (where unwritten reviewer reflexes routinely surface in thread responses), the Chrome University lecture series (where tribal knowledge is partly converted to explicit form by talk), the RenderingNG article series (where the rendering subsystem's tribal knowledge has been more thoroughly converted than most), and the new-contributor onboarding guidance on `chromium.org`. The Linux Foundation's January 2025 announcement of the Supporters of Chromium-Based Browsers fund frames the cross-organization tacit-knowledge transfer as an institutional problem worth investing in; the announcement is the ecosystem-level acknowledgment that the cost is real. ## Technical Drill-Down - [Chromium `docs/` directory (Gitiles)](https://chromium.googlesource.com/chromium/src/+/main/docs/) — the explicit subset; what is here is citable, what is not here is in heads. - [`docs/security/rule-of-2.md`](https://chromium.googlesource.com/chromium/src/+/main/docs/security/rule-of-2.md) — a representative case of tribal knowledge converted to explicit form; the rule operated for years before it was written down. - [`docs/security/mojo.md`](https://chromium.googlesource.com/chromium/src/+/main/docs/security/mojo.md) — the IPC security guidance that converted a substantial body of reviewer reflexes into citable form. - [`blink-dev` archive](https://groups.google.com/a/chromium.org/g/blink-dev) — the public mailing-list record where unwritten reviewer reflexes routinely become visible in thread responses. - [Chrome University on the Chrome Developers YouTube channel](https://www.youtube.com/@ChromeDevs) — "Life of a Pixel" and adjacent lectures; one of the project's main mechanisms for converting rendering tribal knowledge to explicit form. - [Linux Foundation: Supporters of Chromium-Based Browsers (January 2025)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-launch-of-supporters-of-chromium-based-browsers) — ecosystem-level acknowledgment of cross-organization tacit-knowledge transfer as an institutional problem. - [Chromium new-contributor guide](https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md) — the documented portion of the contributor ramp; everything outside this is tribal by definition. --- - [Next: Formal-Informal Channel Split](formal-informal-split.md) - [Previous: Design Document Staleness](design-doc-staleness.md)