A Ground Truth is a versioned, structured model of how a business and its product actually work, precise enough that a person and an AI agent can both build against it and verify against it. In Rootshift it is a Git repository of markdown artifacts that sits next to the code, never inside it, with its own history, owners, and checks.
The definition is strict on purpose: if it is not structured, owned, versioned, and validated, it is not Ground Truth.
Why agents need one
Every company is a pile of documents that disagree. Decks, PRDs, chat threads, a wiki nobody trusts, a founder’s head. For thirty years knowledge management struggled because its only reader was a human who would rather ask a colleague. Now the reader is an agent that reads everything, believes all of it, and ships. Documentation finally has a reader that acts on it, which makes the quality of a company’s knowledge consequential.
Give an agent the whole pile and it inherits every contradiction. Give it a Ground Truth and it inherits the decisions people already made, with the reasons attached.
The seven parts
The folder names are the same on every project:
- 01 Project Context. Goals, audiences, stakeholders, constraints, success metrics, non-goals, open questions.
- 02 Domain Model. Entities, vocabulary, states, business rules, edge cases.
- 03 Capability Specs. Capabilities and their user stories, with Given/When/Then acceptance criteria.
- 04 Engineering Context. Architecture, stack, repository structure, conventions, security, deployment.
- 05 Integration Contracts. External systems, what each owns, the source of truth per field, sync direction, failure behavior.
- 06 Eval Suite. One named check per acceptance criterion, plus the checks that catch regressions.
- 07 Decision Log. Every material decision as an artifact: who, when, why, the alternatives rejected, what changed. Never rewritten, only superseded.
The metadata on every artifact
| Field | What it means |
|---|---|
owner | A named human accountable for the artifact being true. |
status | draft → in-review → approved → needs-revalidation → deprecated. |
confidence | High requires a primary source and human validation. Low means inferred, stale, or conflicting. |
sources | Dated links to where each claim came from. |
last_validated | When a person last confirmed it. |
Approval is an independent judgment. A changed source flips an approved artifact to needs-revalidation, and the work that depends on it waits.
What makes it hold
Three properties are enforced, not suggested:
- Validation state is machine-readable. A readiness gate refuses to dispatch a build that depends on unapproved truth.
- Contradictions are defects. Two artifacts that disagree are a blocking finding. A story that cites a resolved decision as still open is a checker error.
- Gaps become routed work. An agent that reaches something it must not decide writes an open decision, routes it to the owner, and moves on to work it can do.
Gates are calibrated, not maximal. A rule that blocks everything teaches its operator to wave things through, so a hole blocks the story being built, not the whole model.
How one gets built
Knowledge intake starts from what already exists: code and repositories, documents and PRDs, interviews, the live product and its data. An intake agent drafts the model and interviews people for what the documents leave out. Inconsistencies and gaps are part of the deliverable. People then review and approve, artifact by artifact. For the long version, with a real takeover six weeks in, read the foundational essay.