Zachary Lowden
0aee832699
Follow-up to the audit of this directory. Five claims were false; each is corrected IN PLACE per claudedocs/README.md rather than silently edited out. 1. services-a-m-parameterised-client-analysis.md — "`model.findUnique` resolves to `dbRead` in the service source directly" is FALSE on the path these tests drive, and it cost a red batch: six tests across two files, all "expected null not to be null", fifteen sites corrected to dbWrite. `resolveBlockInstance` takes its client as a parameter and uses that local throughout; the `dbRead` spelling cited sits in a function the tests never call. This is the highest-value correction in the set — the document is cited three times by the handover, and the handover's own lesson is that a table right 95% of the time is more dangerous than one obviously rough. 2. services-a-m-handover.md status line — 🔴 MY REGRESSION, introduced by #4280. It named `perf/test-mock-migration-services-a-m` as "the reference". That is the STALE remote this same document's "Landing state" section warns about: it predates the rebase, its history diverges, and it still sits at19e95f05b5. The status line pointed a successor at the one branch the body says not to trust — added by the very change whose purpose was making status claims checkable. 3. Same doc — "2 hold-outs remaining" is now 0 and "the seeding fix has not landed" is now landed; both closed by #4281. 4. notifications-test-coverage-audit — the top three ranked gaps have all been closed by five behavioural suites. Reframed from "NOT VERIFIED" to superseded, and kept explicitly for its METHOD (blast-radius ranking, the fake-PoolClient recorder, the assert-on-behaviour-not-strings critique) rather than its status. 5. typecheck-tests-gap §3 — "that import cannot resolve at runtime either" is wrong. At the doc's own measurement commit the import was already `import type`, so it is erased at transpile. The suite does execute zero tests, but because of a deliberate `describe.skipIf` on KYSELY_PARITY_DATABASE_URL. The section's headline finding is untouched. Also repoints README.md's correction exemplar: it named runner-scouting, which does not use a `(corrected …)` status line — its corrections live in a body blockquote. Every citation here was verified before commit, and two of my own did not survive it: "closed by #4293" was written of a PR that is still OPEN, and commit `632a3da432` — which the handover names as its reference — does not resolve in this repository at all, its branch having been deleted. Replaced with #3973's squash commit533640662d, which does resolve, and the dead SHA is now called out rather than repeated.
2.5 KiB
claudedocs/
In-depth technical documents: RCAs, audits, analyses, handovers, and investigations.
These are not auto-loaded by agents — they cost nothing until someone opens them.
They live here (not in docs/) because they contain operational detail, investigation
methodology, and measured evidence that would be noise in user-facing feature docs.
Status-line convention
Every document that asserts an outcome (a fix landed, a proposal was merged, a measurement holds, a recommendation stands) must carry a status line that names the commit SHA or PR number the claim was true at. This makes the status a claim about a point in history, not about the present, so it can be re-verified rather than re-trusted.
Format
The status line goes immediately after the document's # heading, as a bold
**Status:** paragraph. The first word after the colon is the status category,
followed by the evidence:
# Document Title
**Status:** merged. PR #NNNN (merged YYYY-MM-DD). <one-sentence summary>.
Categories
- merged — the change landed. Name the PR and merge date.
- open — the issue/PR is still open. Name the PR.
- diagnosed, not fixed — root cause known, no fix shipped. Say what would fix it.
- historical snapshot — the doc captures a point-in-time measurement or analysis. Say what it was measured at (commit SHA, branch, date).
- recommendation unchanged — the doc's recommendation still holds. Say when it was last checked.
Corrections
When a status has changed since the doc was written, state the correction in place
rather than silently editing out the old claim. Use the pattern from
typecheck-tests-gap-2026-08-12.md or turbopack-chunk-hash-collision-2026-08-18.md,
which carry a real (corrected …) status line:
**Status (corrected YYYY-MM-DD):** <new status>. <evidence>.
The original text is not removed — the correction block sits above or replaces the old status line, and the body of the document is left untouched.
What NOT to put in a status line
- Internal infrastructure names, hostnames, or deployment details (this repo is public).
- Operational specifics that belong in the private infra repo.
- Claims that require running the codebase to verify (e.g., "coverage is still 32%").
Verification
Re-derive a doc's status against the repository (gh pr view, git log), never
from the doc's own text. An audit that reads each doc's self-reported status instead
of re-checking the repo will get the same wrong answers the doc already has.