Skip to content

A public page promising something nothing tests

Public material is written by a different act from the code, so it drifts ahead of the behaviour and nothing brings it back.

→ published a page that promised more than any test could support

cost when it happens
high
how often
common
area
documentation
verification
recognised by
open-source-maintainer
platform-team
enterprise
engineering-lead

The moment

The page says the system does something. It nearly does. The gap is the kind that a knowledgeable reader would call a difference of emphasis and a user would call a bug, and it exists because the page was written from the design and the code was written from the constraints.

Why it happens

Public material is written once, early, when the intended behaviour is the only behaviour there is. Shipping narrows the design; the narrowing is recorded in commits and tests, and in nothing that anyone reconciles against the page. Nothing on the page marks which sentences are load-bearing.

Why a better model does not fix it

A worker asked to write the page from the design writes an accurate description of the design. The failure is that the page is not derived from anything that changes when the behaviour changes.

What it costs

Trust, which is expensive to regain and is spent by exactly the readers who mattered most — the ones who relied on the sentence. Internally it costs the same as any stale document, plus an argument about whether the page was wrong or the implementation was.

What Majordomus does

Every capability sentence is a claim object with a status — guaranteed, advisory, planned or rejected — the file that implements it and the behavioural case that proves it. The public pages render those objects rather than restating them, so a claim cannot appear on a page with a status it does not have. A guaranteed claim without a real implementation and a real test fails the check. Rejected is a published status with its reasoning, so an idea that was considered and refused stays refused instead of being proposed again.

Before and after

before   page: "Majordomus verifies completion."      code: it verifies what you name.

after    claim finish-contract   guaranteed  lib/finish.sh  test/cases/06_finish.sh
         claim cost-per-outcome  planned     -              -
         (the page renders the status; a guaranteed row with '-' fails the build)

What it does not do

It does not review the wording of a page, and a badly worded true claim is still badly worded. It refuses the pairing of a strong status with no evidence.

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. The page written before the feature open-source-maintainer

    before
    A page describes the capability as it was designed; the shipped version is narrower and the page is never revised.
    after
    Every capability sentence is a claim with a status, an implementation and a test, and the page renders that status.

  2. Somebody procures on the strength of it enterprise

    before
    A published guarantee is relied on in a decision, and it turns out to be an aspiration.
    after
    `guaranteed`, `advisory`, `planned` and `rejected` are distinct statuses shown on the page, and a guaranteed claim without a test fails the build.

  3. Publishing what was rejected platform-team

    before
    An approach that was considered and refused is invisible, so it is proposed again by every reader.
    after
    Rejected is a status that is published with its reasoning, not an absence.

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.

  • A public page describes a capability the code does not fully have. page-ahead-of-code
  • Nothing on a public page distinguishes what is guaranteed from what is intended. no-status-on-claims
  • Public material is written separately from the code and reconciled by nobody. written-separately

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.no-claim-without-test
  • project.use-case-evidence
  • majordomus.use-case-coverage
  • project.derived-files-regenerated

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 →