Reference Documents Need Explicit Authority Domains

A new reference document does not displace existing ones unless you assign authority explicitly. The governance work is domain ownership and conflict-routing rules — not the document itself.

The problem

Repositories and operations guides accumulate reference documents over time. A coding guide here. An architecture reference there. A process doc added when someone remembered to write it down. Each document seemed complete when written.

The problem surfaces later. A future worker asks: which document controls this decision? The process doc and the architecture reference both touch the same subject. The tooling guide has a rule that conflicts with the engineering reference. Nobody wrote down which one wins.

When authority is ambiguous, future workers guess or hedge. They create yet another document, or update the nearest-looking one, or do nothing. The accumulation of "reference" documents with undefined relationships produces more ambiguity than it resolves.

What the fix actually required

A team facing this problem set out to create a central engineering reference document. The surface-level task looked simple: consolidate the conventions, file it, done.

What they discovered was a governance gap, not a content gap.

The real work was:

• Defining an authority domain for each existing document — what territory does this document own?
• Writing a conflict-routing rule: if two documents disagree, which one wins?
• Creating a canonical reference that covered remaining unowned territory
• Recording known gaps explicitly — not filling them with invented policy

Without the first two steps, the new document would join the overlapping pile rather than resolve it.

Gap recording, not policy invention

When building a reference document from current evidence, you will encounter unknowns. A script that nobody documented. A convention that appears inconsistent. A workflow step that was never confirmed.

The wrong response is to write what you think the policy should be and file it as fact.

The right response is to record the gap: "This area is currently undocumented. Known state: X. Policy: unresolved."

A reference document that invents policy becomes governance risk. Future workers cite it. Decisions are made on it. The invented policy solidifies into practice without the review it deserved.

A reference document that records gaps is a useful baseline. It shows what is known, and makes the unknowns visible rather than hiding them behind confident-sounding language.

The broader principle: authority must be assigned, not implied

A new document does not displace existing ones unless you explicitly reassign authority. "The engineering reference covers tooling" is not enough if the architecture reference also covers tooling. The governance act is the assignment — writing down which document owns which domain and what happens when they disagree.

This applies beyond documentation:

• Codebases with multiple overlapping configuration files
• Teams with competing process documents for the same workflow
• Projects where the architecture guide and the implementation guide have drifted into the same territory

Anywhere two documents claim the same territory, future workers face an authority problem. Adding a third document does not help. Explicit domain assignment does.

A second act: ensuring reference documents get found

Creating a reference document completes one governance act. There is a second act that most teams skip: ensuring future workers are required to consult it.

A reference document that can be silently ignored is not an authority. It is a suggestion.

If future workers do not discover the reference before making decisions in its domain, the document is inert. The governance only works when discovery is mandatory — through tooling, process, review gates, or workflow steps that surface the relevant reference before work begins. Otherwise the document exists and is quietly bypassed.

How to apply it

Before creating or consolidating reference documents:

1. Map existing documents and their claimed territory. Identify every overlap.
2. Assign explicit authority domains. Each domain should have exactly one owner document.
3. Write a conflict-routing rule. If two documents disagree, state which one wins.
4. Build the new reference from current evidence. Record what is true; record what is unknown; do not invent policy to fill gaps.

When migrating old documents:

• Use rename detection, not just new file creation
• Sweep for stale references in active documents that still point to old paths or titles
• Scope the migration explicitly — live references only, unless historical references are intentionally included

After the reference is in place:

• Define how future workers will discover and apply it
• If workers can bypass the reference without triggering a review or gate, the document is a suggestion, not a constraint

The governance work is not writing the document. It is making the authority unambiguous and the discovery mandatory.