Skip to content

A hard-won discovery that never became knowledge

A worker learns something expensive about the codebase, uses it once, and it dies with the session because nothing turned it into a durable record.

→ spent an hour discovering something the repository already knew, twice

cost when it happens
medium
how often
common
area
context
recognised by
solo-builder
agency
research-team
ai-native-team

The moment

A worker spends an hour establishing why the integration test is flaky — a clock dependency three layers down — fixes it, and says so. Six weeks later the same flake returns in a different test and somebody spends the hour again.

Why it happens

There was nowhere for the finding to go that anybody would look. A comment in the code says it to whoever opens that file; a chat message says it to whoever was present; a wiki page says it to whoever searches for the right words. None of them is loaded by the next worker, so the default outcome for any discovery is that it evaporates.

Why a better model does not fix it

The discovery was made correctly the first time. The failure is entirely between sessions: nothing converted a finding into something the next worker is given. Better models make the rediscovery faster and no less repeated.

What it costs

The hour, each time. And a subtler cost: because rediscovery is normal, workers stop treating existing code as evidence of a prior decision, and start treating every constraint as something to be worked around.

What Majordomus does

Knowledge is a declared kind, not a folder of notes. majordomus knowledge records one durable statement about the repository with the class of statement it is — fact, convention, constraint, memory or lesson — how it is known (observed, inferred, decided) and how far it has been confirmed. A record whose status is verified must name the evidence it was confirmed against; nothing is confirmed by having been written down.

Knowledge sources are declared in one file, so discovery goes through the version-control index rather than the filesystem: an untracked scratch file is not knowledge, and two machines see the same list in the same order. majordomus context draws on records with class memory when it assembles what the next worker needs.

Before and after

before   finding -> session -> nothing

after    majordomus knowledge add "the integration clock is injected, not read" \
           --class fact --epistemics observed --evidence test/cases/42_clock.sh
         # class memory records are offered to the next context, within budget

How to verify it

Record a finding and start a new session: majordomus context offers it. Mark a record verified without evidence and it is refused.

What it does not do

It does not extract knowledge from a transcript, and it will not store one. A machine extraction produces a candidate, never a verified record — confirmation is a person's act, against evidence that is named.

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. Why that test is flaky ai-native-team

    before
    A worker spends an hour establishing that the flake is a clock dependency; the finding is stated in the session and lost with it.
    after
    The finding is a knowledge record with class `fact` and its evidence, and the next worker is assembled with it.

  2. The client build quirk agency

    before
    The build needs a flag nobody documented; each new person on the account rediscovers it, at a cost of an afternoon.
    after
    It is a knowledge record with class `constraint` — something outside the repository that limits it — found by `search` in seconds.

  3. The approach that cannot work research-team

    before
    An approach is ruled out for a good technical reason; six weeks later it is attempted again.
    after
    The record carries class `lesson` and what the earlier attempt cost, so the second attempt does not start.

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.

  • Something non-obvious about this codebase was worked out from scratch that had been worked out before. rediscovered
  • A worker learned something worth keeping and there was nowhere obvious to put it. no-place-to-put-it
  • Useful findings from a session exist only inside that session. findings-in-chat

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.externalise-decisions
  • project.never-store-transcripts
  • majordomus.minimum-sufficient-context

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 →