Captures the durable learnings from the 2026-07-25 whole-repo documentation
reconciliation as a knowledge-track learning, plus the vocabulary it introduced.
New learning — conventions/reconciling-drifted-docs-tense-tiering-and-a-supersession-ledger.md:
- Tier docs by TENSE, not only by content type. claude-md-content-tiering.md
established "descriptions drift, rules don't" and tiered by content type; that
axis could not say what to do with 41 completed plans, which are neither rules
nor current descriptions. Present-tense docs are defects when stale; past-tense
records are supposed to be stale and get annotated, never rewritten.
- Ledger AND inline notes, because each covers the other's failure: a ledger
alone is a pointer you may not follow, inline notes alone give no changelog
view. Prefer annotation patterns the repo already uses.
- Record what was NOT reversed, or a ledger of only reversals makes every old
doc look suspect and settled decisions get re-litigated.
- Separate "docs are wrong" from "code is wrong" — route code-side findings to a
recommendations doc so a docs diff stays reviewable.
- Verify against the artifact that decides behaviour: the Makefile for commands
(including macro-generated targets a grep misses), the build script for
outputs, imports for source-vs-output, branch history for whether a plan
shipped. An audit that never withdraws a finding has not been checking itself
— one finding here was withdrawn after reading package.json.
- Audit the state that actually runs: a fresh worktree checks out the submodule
PIN, which lagged real HEAD and would have hidden a whole merged feature.
Three structural lessons in "Why This Matters":
- An index describing another document's role is a factual claim that can rot,
and it is worse than the stale document itself — it defeats the reader's
judgement before it engages. This was the tree's single most misleading line.
- Wrong beats absent again, now for commands: README's server runbook documented
every remote-* target without the -test/-prod suffix guard-env requires.
deploy-cycle.md had it right — the defect was a second copy drifting.
- Promoting a doc to "the authoritative list of X" creates a completeness
obligation it did not have as prose, and nothing enforces it.
- A removal is not finished when the code is gone, but when every consumer and
every description of it is gone — travel-memories left a compose service
behind, hidden by a cached Docker image. Local state can mask a breakage
indefinitely, so "it works here" is not evidence.
Overlap with conventions/claude-md-content-tiering.md scored MODERATE (2 of 5
dimensions: same root-cause thesis, overlapping files; different tiering axis
and different prevention), so a new doc was written rather than folding into it.
Flagged in the Related section as a consolidation candidate if a third
documentation learning appears.
CONCEPTS.md — new Documentation cluster (Historical record, Superseded decision,
Plan status) and one flagged ambiguity recording that a present-tense historical
record is not a claim about the current system. These three are now referenced by
CLAUDE.md and both doc READMEs, so they needed defining.
Discoverability check: no edit needed — CLAUDE.md's entry-point table already
surfaces docs/solutions/ with its frontmatter fields and CONCEPTS.md.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
m038andClaude Opus 5
d946eaaa7e