intotheeast-com/docs/solutions/conventions/reconciling-drifted-docs-tense-tiering-and-a-supersession-ledger.md

title, date, category, module, problem_type, component, severity, applies_when, tags

title	date	category	module	problem_type	component	severity	applies_when	tags
Reconciling drifted docs — tier by tense, and record reversals in a ledger	2026-07-25	conventions	documentation	convention	documentation	high	Auditing documentation against the code after a period of undocumented change Deciding whether a stale document should be corrected, annotated, or deleted A plan or milestone describes a feature that was later dropped or replaced Writing or reviewing an index that describes what another document is for Asked whether the docs would pass a review, or to make them pass one A decision is being reversed and the old rationale needs to survive the reversal	documentation-conventions staleness tiering drift supersession decision-log audit verification indexes

Reconciling drifted docs — tier by tense, and record reversals in a ledger

Context

Five weeks after the last documentation pass, this repo's docs described a site that partly no longer existed. /map, /stats, /tracker, Leaflet, a light theme, and hero_image on entries had all been deliberately removed — but several documents still presented them in confident present tense, and nothing marked those documents as historical.

The trigger question was "straighten this out so a repeat review returns ok." The answer depended on a distinction the tree did not encode.

claude-md-content-tiering.md established that descriptions drift and rules do not, and tiered content by type (rules stay in CLAUDE.md, descriptions move to docs/). This pass confirmed that thesis again — every one of 20 verified defects was a description of code, config, or a command; not one was a rule that had gone wrong on its own. But content-type tiering alone did not answer what to do with 41 completed plans and 4 milestone specs, because those are neither rules nor current descriptions.

The missing axis was tense.

Guidance

1. Tier by tense, then treat the halves oppositely

Kind	Files here	Claims	Staleness is	Treatment
Present-tense	CLAUDE.md, docs/reference/, docs/guides/, README.md, CONCEPTS.md	"this is how it is"	a defect	correct against the code
Past-tense	docs/working/plans/, specs/, milestones/, summary.md, pm-analysis.md	"this is what we decided then"	correct and expected	annotate only, never rewrite

A completed plan should be stale — that is what makes it a record. Rewriting 41 plans to match today's code would destroy the audit trail of why each thing changed, and the work is unbounded. The defect was never their staleness; it was that nothing told a reader they were history.

docs/solutions/ straddles the split deliberately: past-tense incident, present-tense guidance. That is why its applies_when frontmatter matters more than its narrative — the frontmatter is the part that must stay true.

2. Ledger plus inline notes — neither alone is enough

Two mechanisms, because each covers the other's failure:

• A supersession ledger (docs/reference/superseded-decisions.md) — one table: what was planned, where it was planned, what is true now, when it changed, why. This is the only thing that answers "what did I change my mind about?" in one place, which is the question a review actually asks. Alone, it has an indirection problem: a pointer you might not follow.
• Inline > **Superseded …** notes at each stale claim, so the claim cannot be read un-corrected. Alone, it has a completeness problem: no changelog view, and coverage is only as good as the annotation pass was.

Prefer the annotation patterns the repo already uses. Here, architecture.md already carried > History: notes and trip-switching.md already carried > **Changed 2026-07:**. Inventing a third convention would have been worse than adopting either.

Add the ledger row in the same commit as the reversal. A ledger that lags is worse than no ledger, because it is trusted — the same failure mode as a lagging plan Status: line.

3. Also record what was not reversed

A ledger of only reversals makes every old document look suspect. This one ends with a short "decisions that were not reversed" section — the pm-analysis.md SKIP list still stands, the weather integration shipped exactly as specified, the stats computation survived and only moved. Without it, a future reader re-litigates settled decisions because the surrounding docs looked old.

4. Separate "the docs are wrong" from "the code is wrong"

An audit against code finds both. Mixing them makes the diff unreviewable and stalls the documentation fix behind a behaviour decision. Route code-side findings to a separate recommendations document and explicitly do not act on them. Here that kept a 300-line docs diff clean while still capturing that make start is broken on any clean checkout.

Documenting a trap is not the same as fixing it — and is the right move when the fix is someone else's call. Per the tiering doc, a gotcha has no natural trigger that opens a file, so a live trap belongs in CLAUDE.md even while its fix stays unscheduled.

5. Verify against the artifact that decides behaviour, not the prose about it

Every finding must come from the thing that actually determines behaviour:

To check	Read
What a command does	the Makefile — including macro-generated targets, which a grep for literal target names will miss
What a build produces	the build script (package.json), not a prose asset table
Whether a file is a source or an output	which file imports it, and how it reaches the page
Whether a feature exists	the absence of its mechanism, not the absence of a mention
Whether a plan shipped	the branch history, not the plan's own Status: line

This is also where an audit catches itself. One draft finding here claimed the asset table was missing four source files; reading package.json showed the table lists esbuild entry points, so imported-only sources were correctly absent. The finding was withdrawn. An audit that never withdraws a finding has not been checking itself.

6. Re-check the baseline before publishing, not only before starting

A long audit races the work it is auditing. This one had its baseline move twice, and each time the convenient state was the wrong one:

• The submodule pin lagged. A fresh worktree checks out the commit the outer repo pins, not the submodule's real HEAD. Auditing the pin would have reported a shipped feature as unbuilt. Move to the real HEAD first, and keep the gitlink out of the commit (see dual-repo-submodule-workflow.md — M user is normal and must not be "fixed").
• The base branch advanced 13 commits mid-audit, independently fixing two findings. Merging the base branch in before opening the PR is what surfaced that. Without it, the branch would have reverted work that was already correct — the worst possible outcome for a cleanup pass, because it arrives disguised as an improvement.

Two habits fall out of this. Merge the base branch in before publishing, and read the conflicts as findings rather than chores — each conflict is the codebase telling you someone else already reasoned about this line. And when the incoming version is better, take it wholesale: here the base branch's map-doctrine wording and plan status were both more informed than the replacements drafted during the audit, so they were kept in full and the audit's own notes were corrected to match. An audit has no special authority over the work it audits.

Why This Matters

An index describing another document's role makes a factual claim that can rot — and it is worse than the stale document itself. The single most misleading line in this tree was docs/working/README.md advertising summary.md as "Project summary / current state", while summary.md described Leaflet, /tracker, /map and /stats. A stale document is survivable — a reader may notice the date, the tone, the odd claim. An index that vouches for it as authoritative defeats that judgement before it engages. When writing an index, treat every "what this file is for" phrase as an assertion with an expiry date.

Wrong beats absent, again — now for commands. The tiering doc found this for paths: an absent fact makes an agent go look; a wrong one makes it act confidently in the wrong place. The same held for README.md's server runbook, where every remote-* command was documented without the -test/-prod suffix guard-env requires. Every documented command failed on the first line. deploy-cycle.md had the rule right the whole time — the defect was a second copy of the knowledge drifting from the first. Fewer copies would have prevented it outright.

Promoting a doc to "the authoritative list of X" creates a completeness obligation it did not have as prose. CLAUDE.md pointed at README.md for "the full make command list"; README then held 7 of ~20 remote-* targets. The pointer was added by a well-intentioned earlier tiering pass. Routing content out of an always-loaded file is right, but the destination inherits a duty to be complete, and nothing enforces that.

Deliberate removals leak. travel-memories was extracted to its own project, its source deleted and services/ gitignored — but docker-compose.yml still declared the service, and CLAUDE.md still claimed it ran on :8082. make start has therefore been broken on every clean checkout since, hidden only because a pre-removal Docker image stayed cached locally. A removal is not finished when the code is gone; it is finished when every consumer and every description of it is gone too. The cached image is the general lesson: local state can mask a breakage indefinitely, so "it works here" is not evidence.

When to Apply

• After any stretch of change that outpaced its documentation, or when asked whether the docs would survive a review
• Before rewriting a stale plan, spec, or milestone — annotate it instead; the record is the value
• When reversing a decision: add the ledger row and the inline note in the reversal's own commit
• When writing an index, a folder README, or any "read X for Y" pointer — that pointer is a claim
• When removing a service, route, feature, or dependency: sweep for consumers and for prose that describes it, including compose files, always-loaded instruction files, and demo fixtures
• When promoting any document to authoritative for a list — decide who keeps it complete
• Before auditing a repo with submodules: confirm you are on the state that actually runs

Examples

Tense-marking a historical spec, without rewriting it

milestones/milestone-2.md still opens with its original goal — that is the record. The banner sits directly beneath it, so the stale claim cannot be read alone:

**Goal:** A `/map` page shows all entries as markers on an interactive Leaflet.js map, …

> **Superseded — written 2026-06-21. Neither the `/map` page nor Leaflet exists.**
>
> - **No `/map` route.** The map renders inline on the trip page via the single shared partial
>   `templates/partials/entry-map.html.twig` (R1, retired 2026-07-04).
> - **Leaflet + OpenStreetMap tiles → MapLibre GL JS** (R4, 2026-06-20).
>
> The *substance* of this spec survived — markers per entry, chronological route line, popups,
> bounds fitting — it all lives in `MapUtils.initEntryMap()`. Only the page and the library changed.

Separating "the idea won" from "this implementation lost" is what stops a future reader concluding the whole spec was a dead end.

An index that vouched for a stale document

-| `summary.md` | Project summary / current state |
+| `summary.md` | **Historical** wrap-up of the original four-milestone branch (2026-06-21).
+  *Not* the current state — for that read [`../reference/architecture.md`](../reference/architecture.md) |

A source relationship that never existed

CLAUDE.md asserted a build dependency between two unrelated things. css/ is hand-authored and served directly; css-compiled/ is esbuild output from the CSS imports inside js/src/*.js:

-- `css-compiled/` and `fonts/` are generated (sources: `css/style.css`, `css/tokens.css`)
+- `css-compiled/` and `fonts/` are **esbuild output from the imports inside `js/src/`** — *not*
+  from `css/`. Everything in `css/` is hand-authored and served directly (`assets.addCss` in
+  `partials/base.html.twig`), never compiled.

The failure this invited: an agent wanting to change a font edits css-compiled/main.css — a generated bundle — because the rule named css/style.css as its source and that file does not contain it. The next make build-assets silently reverts the edit.

Proving a breakage instead of inferring it

Reasoning that a missing directory would break a build is not evidence. Running it is:

$ docker compose build travel-memories
unable to prepare context: path ".../services/travel-memories" not found

The follow-up mattered more than the failure: a cached travel-blog-intotheeast-travel-memories:latest image explained why make start still worked on the main checkout but failed in every new worktree. Without that check the finding would have been reported as "broken everywhere" and been wrong.

Related

• claude-md-content-tiering.md — the content-type tiering axis and the "descriptions drift, rules don't" thesis this learning extends with a tense axis. Consolidation candidate: the two overlap on root cause and on the files they touch; if a third documentation learning appears, consider merging all three into one documentation-maintenance doc.
• ../architecture-patterns/retiring-a-consolidated-grav-sub-page.md — the mechanics of the retirement that produced ledger rows R1, R2 and R5. That doc covers removing the page; this one covers removing the claims about the page.
• ../architecture-patterns/dual-repo-submodule-workflow.md — why a fresh worktree's user/ sits at the pin rather than at HEAD, which is the audit-baseline trap in §6.
• ../integration-issues/stale-grav-version-blocks-api-plugin-install.md — the same rot in the deploy-config domain: a version number that went stale and broke an install.
• docs/working/specs/2026-07-25-docs-reconciliation-design.md — the design and the verification table for this pass.
• docs/working/2026-07-25-doc-drift-recommendations.md — the code-side findings deliberately not acted on, including the compose breakage and a proposed repeatable make docs-check.