← Patterns

Lists and pages that stay true
AI helps us move at lightspeed. There's no time to write everything up. So I've used my personal voice and based this on my actual work, to be able to share in real time what I'm doing with the teams I work with.

Lists and pages that stay true

Documentation where every sentence has evidence

Each factual sentence on a page is listed beside its evidence, so a change to the sentence, or to the thing it describes, fails a check.

One of 15 patterns I've found working with AI coding agents. An agent drafted the words from my notes, and I haven't edited them yet. See all 15, or read how they are made.

An agent drafted the words from my notes, and I haven't edited them yet. The code was run before it went in.

The problem

Documentation drifts because nothing fails when a sentence stops being true. A page says sessions time out after 30 minutes. Someone changes it to 15 in the code. The page is now wrong, every check is green, and the first person to notice is a reader.

Checking pages against the code is not enough either. Code shows what was set up, not what is running. In one codebase a page said for three months that a feature was in active use, while the service behind it had recorded nothing at all.

The idea

Keep a ledger, a list of every factual sentence on a page, word for word, each with one piece of evidence. The evidence is one of a few kinds: a file and a string it should still contain, a command with the date it was run and what it returned, or a named person who vouches for it, with a date.

A check then fails in three ways. A listed sentence is no longer on its page. A file no longer contains its string. Or a command's result or a person's word is older than an agreed limit. Each one sends someone back to the evidence, which is the point.

A version small enough to read

A three-sentence page, two code files, and a ledger with one row per sentence.

claims-ledger/check.ts
// Every factual sentence on a page has a ledger row with its evidence.
// Run: bun check.ts
type Evidence =
| { kind: "code"; file: string; mustContain: string }
| { kind: "command"; run: string; result: string; on: string }
| { kind: "person"; who: string; on: string };
type Claim = { sentence: string; evidence: Evidence };
const MAX_AGE_DAYS = 14; // a command's result goes stale
const page = `Sessions time out after 30 minutes of inactivity.
Exports are written as CSV.
The nightly backup completed every night this month.`;
const code: Record<string, string> = {
"src/session.ts": "export const IDLE_TIMEOUT_MINUTES = 30;",
"src/export.ts": "export const format = 'csv';",
};
const ledger: Claim[] = [
{ sentence: "Sessions time out after 30 minutes of inactivity.", evidence: { kind: "code", file: "src/session.ts", mustContain: "IDLE_TIMEOUT_MINUTES = 30" } },
{ sentence: "Exports are written as CSV.", evidence: { kind: "code", file: "src/export.ts", mustContain: "'csv'" } },
{ sentence: "The nightly backup completed every night this month.", evidence: { kind: "command", run: "backup-report --month", result: "30 of 30 succeeded", on: "2026-10-30" } },
];
function check(page: string, code: Record<string, string>, ledger: Claim[], today: string): string[] {
const problems: string[] = [];
for (const c of ledger) {
if (!page.includes(c.sentence)) problems.push(`"${c.sentence}" is no longer on the page. Update its row, or delete it.`);
const e = c.evidence;
if (e.kind === "code" && !(code[e.file] ?? "").includes(e.mustContain))
problems.push(`"${c.sentence}": ${e.file} no longer contains ${e.mustContain}. Check the sentence is still true.`);
if (e.kind !== "code") {
const age = (Date.parse(today) - Date.parse(e.on)) / 86_400_000;
if (age > MAX_AGE_DAYS) problems.push(`"${c.sentence}": its evidence is ${age} days old. Run it again and record the result.`);
}
}
return problems;
}
const report = (name: string, p: string[]) => console.log(`${name}:\n ${p.length ? p.join("\n ") : "ledger ok"}`);
report("On 2026-11-05", check(page, code, ledger, "2026-11-05"));
report("The timeout changed to 15 in the code", check(page, { ...code, "src/session.ts": "export const IDLE_TIMEOUT_MINUTES = 15;" }, ledger, "2026-11-05"));
report("Someone rewrote a sentence", check(page.replace("as CSV", "as CSV or JSON"), code, ledger, "2026-11-05"));
report("On 2026-11-20", check(page, code, ledger, "2026-11-20"));

Run with Bun, a JavaScript runtime, it prints:

What the check says
On 2026-11-05:
ledger ok
The timeout changed to 15 in the code:
"Sessions time out after 30 minutes of inactivity.": src/session.ts no longer contains IDLE_TIMEOUT_MINUTES = 30. Check the sentence is still true.
Someone rewrote a sentence:
"Exports are written as CSV." is no longer on the page. Update its row, or delete it.
On 2026-11-20:
"The nightly backup completed every night this month.": its evidence is 21 days old. Run it again and record the result.

The message for a changed file asks whether the sentence is still true, not how to make the string match. Matching the string is the cheap fix, and the wrong one.

Where the plain form falls short

The plain form is a link check: every reference on the page resolves. I've seen these get through it.

  • A sentence is edited and its evidence is not. Holding the sentence word for word means any edit sends someone back to its row.
  • Evidence that was true once. A command run months ago tells you little about today. Giving command and person evidence an age limit, such as fourteen days, makes it be run again.
  • Counts typed into prose. A page said one number of screens while the list it described held another. Counts computed from the source when the page is built cannot disagree with it.
  • A known defect is fixed and the page still discloses it. Turning the evidence round helps here. The row names the string the fix will add, so the check fails once the fix lands, until someone updates the page.

Trade-offs

  • It only holds what is in the ledger. A new factual sentence with no row passes. A reader who has not seen the ledger, which can be an agent, has to read the published page and ask of each sentence whether it is true.
  • Every sentence costs a row. Pages with many claims grow long ledgers. Start with one page that people rely on.
  • Evidence that still matches is not a true sentence. The file can contain its string while the sentence around it has become misleading. The check narrows the problem; it does not settle it.

When to use it, and when not to

It suits pages people act on: how the product handles their data, what it promises, how it is run. It is too heavy for explanation and advice, which are not claims, and for notes that only the team reads.

Example. The claims ledger, on GitHub

A draft skill for this pattern

A skill is a short set of instructions you give a coding agent so it applies a pattern the way you would. Copy the text below into a file called SKILL.md, in the folder your coding agent reads skills from. In Claude Code, Anthropic's coding agent, that is .claude/skills/claims-ledger/. It is a draft, and I haven't tried it on anyone else's project yet.

claims-ledger/SKILL.md
---
name: claims-ledger
description: Use when writing or maintaining documentation, a status page or a public statement whose sentences describe what the system does, so that a sentence that stops being true fails a check. Keeps a ledger of factual sentences, each with its evidence.
---
# Claims ledger
Documentation drifts because nothing fails when a sentence stops being true.
A ledger lists each factual sentence beside its evidence, and a check fails
when either side moves.
## Before you start
Decide which sentences are claims. A claim says what the system does or did:
a timeout, a format, a schedule, a count. Opinion, advice and explanation are
not claims. Start with one page.
## Build it
1. A ledger row holds the sentence, word for word, and one piece of evidence.
Use a few kinds:
- code: a file and a string that file must still contain;
- command: what was run, the date, and the one-line result;
- person: who vouches for it, and the date.
2. The check fails when a ledger sentence is no longer on its page, so
editing a sentence sends someone back to its evidence.
3. It fails when a code file no longer contains its string. The message says
to check the sentence is still true, not to fix the string.
4. Command and person evidence expires. Pick an age (fourteen days is a
reasonable start) and fail when evidence is older.
5. Never type a count into prose. Compute it from the source at build time.
6. For a known defect, invert the evidence: name the string the fix will
add, so the check fails once the fix lands, until someone updates the
page that discloses the defect.
## Prove it can fail
Change a value in the code, rewrite one sentence, and move the clock past the
age limit. Each should fail with its own message.
## What it does not do
It holds only the sentences in the ledger. A new factual sentence with no
row passes. Code shows what was set up, not what is running, so prefer a
command's result for anything about live behaviour. A citation that resolves
is not the same as a sentence that is true; for that, have a reader who has
not seen the ledger read the built page and question each sentence.