Skip to content

Nobody can reconstruct where the milestone actually is

Progress is an aggregate that exists only in people, because the parts it aggregates were never recorded in a form anything can add up.

→ was asked how far the milestone had got and had to go and ask four people

cost when it happens
medium
how often
common
area
work-tracking
observability
recognised by
engineering-lead
enterprise
platform-team
agency

The moment

"How far along is the migration?" The honest answer takes two days and four conversations, and it is still an estimate. The number that gets reported is somebody's impression, stated with a decimal point.

Why it happens

Progress is an aggregate. Aggregating requires that the parts exist as facts — this item is finished, this one is blocked on that one — and they do not: they exist as impressions in the people who did the work. A tracker holds a shadow of them, updated by hand, at the moments when someone remembered.

Why a better model does not fix it

Asking a model to estimate progress from a repository produces a plausible number with no derivation. The problem is not the estimate; it is that a derivable fact is being estimated at all.

What it costs

Planning decisions made on numbers that were felt rather than computed, and a reporting ritual that consumes senior time every week to produce something everyone quietly discounts.

What Majordomus does

A milestone is an outcome specification: the problem that exists today, the outcome that ends it, and the evidence that will prove it reached. Issues reference the milestone; the milestone references no issue, so it never has to be edited when the work under it is re-planned. Progress is derived from the issues that name it and the events they recorded, every time it is read. Evidence is a command or an artifact with its result and its commit, not a sentence. The roadmap page and the tracker are projections of the same files.

Before and after

before   "about seventy per cent"       (source: a feeling)

after    $ majordomus plan
         M003  session-knowledge-integration
           DONE 7   ACTIVE 2   READY 1   BLOCKED 4   (derived, from 14 issues)
           evidence: 2 of 3 covered — 'session_nodes_reference' uncovered

What it does not do

It does not estimate a date and it does not weight items by size. It reports the derived state of the graph, which is a different and more defensible thing than a percentage.

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 Monday number engineering-lead

    before
    A progress figure is assembled from three conversations and presented as though it were measured.
    after
    Progress is derived from the issues that name the milestone and the events they recorded; the arithmetic is visible.

  2. A quarter that cannot be reconstructed enterprise

    before
    Six months later, nobody can say when a milestone was reached or on what basis it was called reached.
    after
    The milestone declares the evidence its outcome requires, and each piece is recorded with the command and the commit that produced it.

  3. The client update agency

    before
    Status for a client is reconstructed weekly, by hand, from memory and branch names.
    after
    `plan` reads the model and reports the derived state; the report is the same one the team reads.

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.

  • Answering "how far along is this" requires asking several people. ask-four-people
  • Progress is reported as a percentage that nobody can show the arithmetic for. percentage-invented
  • The repository cannot say what is finished without a person interpreting it. no-derivable-state

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.project-integrity
  • majordomus.roadmap-integrity
  • majordomus.dag-integrity
  • project.no-counts-in-prose

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 →