Ground truth as an organising principle

A release goes out. Someone asks in a channel whether the new permissions check made it in. Four answers arrive within a minute.

The board says the ticket is in code review. The release notes, generated from ticket titles, do not mention it. An engineer says “yes, that went in Tuesday.” Someone else says they thought it was pulled. The channel spends eleven minutes resolving this, which ends when a person opens the repository, searches, finds the merge commit, and posts a link.

That last step is the interesting one, and it happens in every company, constantly, without anyone noticing what it means. When the answers disagree, everybody knows which one wins. Nobody argues with the merge commit. There is no debate about whether the repository is right, because the repository is not a claim about the work, it is the work.

That instinct, the one that makes an engineer go to the source when the answer actually matters, is a principle that most organisations use dozens of times a day and have never written down. Writing it down changes quite a lot.

Copies and originals

Every record in a software organisation is one of two things. It is either the thing itself, or a description of the thing.

The repository is the thing. If a line of code is in main, the behaviour exists, regardless of what anyone believes. There is no gap between the record and the reality because there is no gap to have. Same for the deploy log, the merge, the reviewer’s approval, the CI run. These are events that happened, recorded by the system they happened in.

The ticket is a description. The roadmap is a description. The status report, the standup note, the spreadsheet the programme manager keeps, the slide in the quarterly review, the architecture diagram on the wiki: all descriptions. Each one was true at the moment it was written and started degrading immediately.

This distinction is not a philosophical nicety. It has a direct operational consequence: descriptions drift, and the rate of drift is proportional to how much human effort is required to keep them in sync divided by how much anyone cares in the moment. That ratio was survivable when work moved slowly. It is not survivable now, and it is worth being precise about why. Drift is not proportional to time. It is proportional to events. A description of a system that changes four times a week degrades four times as fast as one that changes once a week, and no amount of discipline changes the arithmetic.

So the question every organisation has to answer, and most have answered by accident, is: which artefact is authoritative, and how does everything else derive from it?

Three ways organisations answer this

The tracker is authoritative. This is the most common answer and it is almost always implicit. The board is where planning happens, where reporting comes from, where leadership looks. Nobody decided this. It happened because the tracker was the thing executives could read.

The consequence is that reality has to be typed into the authoritative system by hand, which means the authoritative system is a description maintained by the least motivated participant at the moment of lowest motivation. Every agile ceremony in existence is a scheduled correction for this. And when work rate goes up by three, the correction cadence does not, so the gap opens faster than the ceremonies close it.

Nothing is authoritative, we ask people. Common in small teams and genuinely effective at small scale. Seven people in a room have a shared model that is more accurate than any tracker. It fails at exactly the point where the number of people who need to know exceeds the number who can be in one conversation, and it fails badly, because the transition is invisible. The team keeps using conversation as the source of truth for months after it stopped working, and the symptom is that different parts of the company confidently believe different things.

Source control is authoritative and everything else derives from it. Rarer, and it is the position this series argues for. The repository is the record. The tracker becomes a view of the record rather than a competing claim about it. Status is not typed, it is derived: the branch exists, the pull request is open, the checks pass, the review is approved, it merged, it deployed.

The third option has a property the other two lack. It cannot drift, because there is no copy being maintained. There is a derivation, and derivations are either correct or broken, which is a much better failure mode than “gradually wrong by an unknown amount.”

What “derive, do not maintain” actually looks like

Made concrete, because the principle is easy to nod at and easy to misapply.

A ticket does not have a status that someone sets. It has a status that is computed. No branch referencing it: not started. Branch exists, commits present, no pull request: in progress. Pull request open: in review. Merged to main: code complete. Deployed to the environment where it can be observed: done, but only if the acceptance criteria evaluated true.

That last clause is doing heavy lifting and it is where this principle stops being about status reporting and starts being about correctness. “Merged” is not the same as “done.” Merged means the change exists. Done means the change achieves what was asked. If you derive done from merged you have built a fast, honest, useless system, because it will confidently report completion for work that does not do the thing.

So ground truth as a principle has two halves that must travel together. Read the state from the repository, because that is what cannot drift. And check the outcome against criteria that a machine can evaluate, because otherwise the state you read is answering the wrong question. Reading ground truth from GitHub or GitLab or Bitbucket, linking every pull request to its ticket, gating done on criteria rather than on merge, and writing the derived status back into whichever tracker your organisation uses: that combination is the whole design, and it is what GroundTruth implements. But the principle is separable from any product, and if you build it yourself the principle is the part that matters.

no branch referencing it        -> not started
branch, commits, no PR          -> in progress
PR open                         -> in review
PR merged                       -> code complete
code complete + criteria met    -> done

The second-order effects

Once you take this seriously, a surprising number of arguments dissolve, and a few new ones appear.

Status meetings shorten or disappear, because their content was reconciliation and reconciliation is now continuous. What remains is the part that was always valuable and always crowded out: deciding what to do about what is true.

“How is it going” stops being a social question. Right now, asking about progress is partly an interpersonal act, which is why the answers are shaped by how the person feels about the asker and how the week has gone. Deriving it from the repository takes the interpersonal load off, and I think this is underrated. A lot of the misery of status reporting is that it feels like being asked to account for yourself.

Estimation gets better inputs, because you finally have accurate cycle times rather than the gap between two manual state changes that were both entered late.

And the new argument that appears: what happens when the derivation is wrong? It will be. A branch named badly, a pull request that touches four tickets, work that happened outside the repository. If the answer to “why does it say that” is a shrug, you have replaced a system that was slow and honest with one that is fast and opaque, and that is a downgrade. Every derived status needs to be traceable back to the specific evidence that produced it and reversible by a human who disagrees. This is not a feature to add later. It is the price of admission for automating a system of record at all.

Where this breaks down

The honest limits, and the first one is significant enough that it disqualifies the whole approach for some teams.

Not all work is in source control. This is the big one. If your team’s real changes happen in a low-code platform, a CMS, a data warehouse configured through a console, an ML pipeline with weights that live elsewhere, or infrastructure that is genuinely changed by hand, then the repository is not ground truth for you, it is a partial view. You can still derive what is derivable, but the guarantee weakens exactly in proportion to how much work happens outside, and a system that confidently reports on 60% of your work while silently ignoring the rest is arguably more dangerous than one that reports on nothing. Be suspicious of anyone who tells you otherwise, us included.

Source control is authoritative about code, not about value. The repository knows a change merged. It does not know whether anyone wanted it, whether it helped, or whether the feature is being used. Ground truth is a strong principle for execution and says nothing at all about whether the execution was worth doing. A team that becomes excellent at deriving truth from the repository can build precisely the wrong thing with perfect fidelity and an immaculate audit trail.

Derivation encodes a workflow, and workflows vary. The mapping I gave above (branch equals in progress, merge equals code complete) assumes trunk-based development with reasonably short-lived branches. Long-lived feature branches, stacked pull requests, monorepo release trains and heavy cherry-picking all break it in different ways. The principle survives, the specific mapping does not, and any tool that hardcodes one mapping will fit some teams badly.

And there is a cultural cost I do not want to skate past. Deriving status from source control means the system observes the work continuously. That is a surveillance capability whether or not you intend it as one, and how it feels depends entirely on what you do with it. Used to keep a board honest, it is relief. Used to compare individuals’ output, it is corrosive, and it will not take long for people to notice which one you are doing. The technology does not decide this and neither does the vendor. Your management culture does, and a team that does not trust its leadership will read automated observation as exactly what it fears.

The takeaway

Every record in your organisation is either the work or a description of the work, and descriptions drift at a rate proportional to how often things change. Source control is the only artefact that cannot drift, because it is not a copy.

Making it authoritative, and deriving everything else from it rather than maintaining a parallel copy by hand, resolves a great many small arguments at once. It requires two halves together: read state from the repository, and gate completion on criteria a machine can check. And it requires every derived claim to be traceable and reversible, or you have traded a slow honest record for a fast opaque one.

The next piece looks hard at the artefact this displaces. The tracker was the right tool for a world it no longer describes, and understanding exactly what it assumed explains why it became the weakest link rather than merely an annoying one.