Skip to content

Code that quietly contradicts a written decision

The decision was recorded and the implementation went the other way, because nothing relates a decision to the paths it governs.

→ found code that contradicted a decision the repository had written down

cost when it happens
high
how often
occasional
area
decisions
governance
recognised by
open-source-maintainer
engineering-lead
ai-native-team
platform-team

The moment

The architecture decision is written, accepted and unambiguous. The implementation does the thing it rejected. Nobody defied the decision; the change was made by someone who had never seen it, and reviewed by someone who had forgotten it.

Why it happens

A decision record is a document in a directory. The work happens in files somewhere else. Unless something relates the two, the decision is discoverable only by a reader who already suspects it exists — which is the reader who did not need it.

Why a better model does not fix it

The worker was not given the decision. Nothing about capability changes which documents reach a session; that is a retrieval question with a deterministic answer, and it should be answered by resolution rather than by inference.

What it costs

A design erodes one reasonable change at a time. By the time it is noticed, the system does something nobody chose, and reversing it costs more than the original decision did — so usually the decision is quietly rewritten to match the code.

What Majordomus does

A decision names what it put in force, as typed references: a rule of the effective set, a claim, a file, a behavioural test. Every reference is validated, and the knowledge graph turns each into an edge, so the reverse index — what this rule, this file or this test was decided by — is derived rather than authored twice. Scoped context documents attach to the paths they govern, and context affected reads a change set from git and reports which documents and scopes it touches, including a tracked source whose document is now due for review.

Before and after

before   .ai/repo/adrs/0007-….md      (accepted, unread)
         lib/skills/registry.rs       (does the rejected thing)

after    $ majordomus context affected --staged
         lib/skills/registry.rs  tracked by adr-0007 "skills are data, not registrations"

What it does not do

It does not judge whether a change contradicts a decision — that is a reading, and a person does it. It makes sure the decision is in front of the person and the worker doing the reading, and that superseding one is an explicit, reviewable act.

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. An ADR nobody was given ai-native-team

    before
    The decision is in the ADR directory; the worker was given the root instruction file and the diff.
    after
    A decision names what it put in force as typed references, so the rule, the file and the test it governs are edges, not prose.

  2. Caught in review, again open-source-maintainer

    before
    The reviewer is the only mechanism connecting a written decision to a contribution that breaks it.
    after
    The reverse index — what this file was decided by — is derived from the decision''s own references.

  3. A design abandoned by accident engineering-lead

    before
    A sequence of individually reasonable changes leaves the system doing what an ADR explicitly ruled out.
    after
    The decision is superseded deliberately, with the replacement naming it, or it stands and the change is refused.

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 decision is written down somewhere and the code does the opposite. written-and-ignored
  • The architecture decisions are recorded and no session has ever loaded one. adr-nobody-reads
  • Nothing connects a decision to the files it constrains. no-link-to-code

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

  • majordomus.adr-integrity
  • majordomus.context-integrity
  • majordomus.externalise-decisions

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 →