Skip to content

Three copies of one explanation, and no way to tell which is current

Every hand-maintained copy of a fact drifts on its own schedule, and a reader cannot tell which copy is the current one.

→ found the same thing explained three times, slightly differently

cost when it happens
medium
how often
constant
area
documentation
recognised by
platform-team
agency
open-source-maintainer
ai-native-team

The moment

The retention behaviour is explained in the README, in a reference document and on a page of the site. The three descriptions differ. Two of them were true once. There is no marking on any of them to say which.

Why it happens

Writing a second explanation is easier than finding and linking the first, especially when the first is in a document with a different audience. Each copy is created reasonably, and from then on the maintenance cost is multiplied while the maintenance attention is not.

Why a better model does not fix it

A worker asked to update the documentation updates the copy it was shown. It cannot know that two others exist. Asking it to search for duplicates first is asking inference to do a job that a derivation would do exactly.

What it costs

Readers act on stale copies. Contributors update one and are corrected. And the accumulated divergence makes any single document untrustworthy, so people ask a person instead — which is the cost the documentation existed to avoid.

What Majordomus does

Each fact has one canonical home, and everything else that shows it is a projection with a check. The layer's scoped documents own their directories; the policy owns the rules; the capability declarations own the interface; the plan owns the status. The site, the reference documents and the provider bootstraps are generated from those, and a generated file that differs from what its source produces fails the check. Where prose would state a number, the rule is to state the command that computes it.

Before and after

before   README.md            "records are kept for 90 days"
         docs/RETENTION.md    "records are kept for 30 days"
         site page            "records are kept indefinitely"

after    policy.yaml          ledger.retention_max_lines: 5000
         everything else      generated from it, and drift-checked

What it does not do

It does not detect that two hand-written paragraphs say the same thing. It removes the need for the second paragraph by making the places that would have held it into outputs.

What this looks like

Concrete situations, one per audience. Each is declared in the moment's front matter, so the before and the after are data rather than prose a page could drift from.

  1. README, reference, site platform-team

    before
    One behaviour is described in the README, in a reference document and on a page; two of the three are out of date and none says so.
    after
    One canonical statement; the others are projections of it, regenerated and drift-checked.

  2. The onboarding document agency

    before
    Every engagement produces a fresh onboarding document that duplicates the repository''s own conventions and then diverges from them.
    after
    Conventions live in scoped context documents in the repository, and the onboarding path is a pointer to them.

  3. A worker given all three ai-native-team

    before
    A worker is pointed at documentation containing three descriptions and has to guess which to follow.
    after
    There is one description, and its provenance is stated on the page it appears on.

How you would know

The observable symptoms this moment declares. They are the questionnaire on the index and the input of majordomus why diagnose; nothing else defines them.

  • The same behaviour is explained in more than one document, in different words. same-thing-thrice
  • A reader cannot tell which of several explanations is the current one. which-is-current
  • Changing a behaviour means remembering to update several documents. update-all-copies

Where this lives in the tool

Everything below is read out of this moment's own front matter and resolved against the repository. A name here that did not exist would fail validation.

the commands that answer it

the capabilities of the executable that answer it

what it supervises — derived from the claims below

the claims that back this page, and the evidence behind each

the rules that govern it

  • project.context-locality
  • project.derived-files-regenerated
  • project.no-counts-in-prose
  • majordomus.context-integrity

the use cases that show the way out

If this one is familiar, so is the next

What this moment names, what names it, and what shares its area, audience or tags. The second and third are derived; only the first is written down.

All 38, and how they connect to the tool →