Files
ersatztv/docs/decisions/records/docs/no-session-narrative.md
T
timothy 6a4265d81d
Build ErsatzTV Image / Delimiter ban (release path) (push) Successful in 40s
Build ErsatzTV Image / Build & test (.NET) (push) Successful in 8m30s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (push) Successful in 6m16s
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (push) Successful in 5m52s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (push) Skipped
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (push) Skipped
Build ErsatzTV Image / Build & push image (amd64) (push) Failing after 17s
feat(784): a doc records the end state — generalize the no-session-narrative rule (#811)
Co-authored-by: Timothy <timothy@noreply.gitea.tblindustries.be>
2026-08-22 00:23:22 +00:00

9.9 KiB

key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
key title status since supersedes superseded-by rule signals mechanics
docs.no-session-narrative 2026-08-21 — a doc records the end state; the path to it goes in the commit message, not the artifact (#784) active 2026-08-21 none none Every durable artifact — an in-repo `docs/` page, a skill, a README, a code comment, an Obsidian vault page — records the END STATE. The path to that end state goes in the commit message, the Gitea issue, or the issue's `## Closing record`; it does not go in the artifact. Concretely: **a review finding is answered in the commit message, and only the corrected claim enters the doc.** Naming the destination is load-bearing — "do not write it in the doc" with no home loses the knowledge, and this repo has the inverse failure on record too (#542, where a pruned narrative turned out to be the only copy). THE TEST IS WHO BENEFITS: if only the author's timeline explains why a sentence is there, it is narrative and belongs in the commit; if a reader who never saw the session would act differently knowing it, it is a finding and stays. Session narrative reads as: first person or session chronology ("I initially thought", "an earlier draft counted", "my first attempt returned 0"), a correction of a belief the reader never held ("this was wrong, actually X" where only X matters), relative time ("earlier today", "currently investigating"), or a blow-by-blow diagnosis standing in place of the conclusion. THE CARVE-OUT, which must be stated or the rule gets over-applied — reader-facing history that must survive: a decision record's `supersedes`/`superseded-by`; a dated measurement or an explicitly stated snapshot boundary; a TESTED-AND-REJECTED negative result, kept so nobody re-proposes it on plausibility; the *why* behind a non-obvious choice; and a trap together with its consequence. `docs/decisions/records/**` and `docs/decisions/archive/**` are exempt WHOLESALE: a record narrating how a rule was got wrong is carrying the rationale it exists to carry. ENFORCEMENT IS ADVISORY ONLY — `scripts/check-doc-narrative.py`, run non-blocking from the `docs-reminder` job over ADDED lines. It is a string predicate over prose and may never become a blocking gate. no session narrative in docs · the reader never saw the earlier draft · who-benefits test · answer a review finding in the commit message not the doc · end state versus path to it · earlier draft · first version of this table · my first attempt · relative time in a doc · carve-out for dated measurement and snapshot boundary · tested-and-rejected negative result · decision records are exempt on purpose · advisory not blocking · string predicate over prose · paths: `scripts/check-doc-narrative.py`, `.gitea/workflows/pr-checks.yml`, `docs/handoffs/chicorytv-issue-queue.md`, `docs/defect-shapes-773.md` · issues: #784, #773, #767, #743, #542 The RULE is about every durable artifact; the DETECTOR's population is narrower and is stated here so a row in it never reads as coverage it does not have. `scripts/check-doc-narrative.py` scans `docs/**/*.md` minus `docs/decisions/**` (exempt wholesale, in both modes), plus root-level `*.md`. Skills under `.claude/`, `web/`, and every other nested markdown file outside `docs/` are OUT of its scope and stay a human judgement. It warns and exits 0 on every path — bad argument, unresolvable ref, unreadable file, unhandled exception — asserted per argument shape in `scripts/tests/test_check_doc_narrative.py`, not only in prose, EXCEPT the unhandled-exception arm, which is a bare `except` no test exercises and is recorded as unproven rather than implied. The invariant is held at the JOB level too (`continue-on-error` on both steps): a script that returns 0 does not keep a job green if a setup action fails. Every knob DEMONSTRATED to break the parse has a row in `FORMAT_KNOBS` in the test file; the user and system config files are removed from the picture entirely so an unnamed one cannot reach it. Three separate review rounds each found ONE more knob turning a real hit into a clean-looking `scanned 0 file(s)`, so the third fix removed the surface rather than naming a fourth knob — a completeness claim over the knob space would be exactly the enumeration that failed three times. COVERAGE BOUNDARY, written once so it is not rediscovered one clause at a time, and naming the clauses rather than a category because a category is where the last mis-sort hid. MUTATION-PROVEN: the parse path (hunk state, the `` marker, the `diff --git` reset, `splitlines`, the population count, `re.IGNORECASE`, the SCANNED-NOTHING return) and five pins — `core.quotePath=false`, `--find-renames`, `--dst-prefix`, `--no-ext-diff`, `--no-color`. UNPROVEN and defensive, recorded as such rather than implied to be covered: `-U0` (the context arm handles any `-U`, so removing it reddens nothing), the `GIT_CONFIG_GLOBAL`/`SYSTEM`/`NOSYSTEM` overrides (which exist for the UNNAMED knob and therefore cannot be witnessed — the script says so itself), `--src-prefix`, the `+++ /dev/null` deletion arm, the malformed-`@@` arm, the stderr relay, `git()`'s `OSError` return, `run_all`'s failure sentinel, `open(errors=)` and the top-level `except`. Both lists ENUMERATE; neither is a universal over the file, and a clause on neither list has simply not been measured. `--diff` scans only lines ADDED in the PR (with rename detection, so a `git mv` does not re-flag a file's pre-existing content) and reports `SCANNED NOTHING` rather than a clean-looking line when it cannot resolve the base. `--all` sweeps the tracked corpus from `git ls-files`, never a filesystem walk (#778). Two consequences of added-lines-only are deliberate and stated so they are not mistaken for coverage: a file MOVED into the population (`web/x.md` to `docs/x.md`) is never scanned by any PR, and neither is anything already in the corpus. `--all` is the only thing that sees either, which is why the sweep is a task a person runs rather than a job.

The rule already existed, correctly stated, and scoped to exactly one file. The kickoff handoff said a paragraph of narrative there is a tax paid by every future session, because that file is pasted into every session. That reason is file-specific. The general reason is broader and applies to every doc in the repo: a reader coming to a doc cold never saw the earlier draft, so "we previously got this wrong" carries nothing they can act on.

This is the recurring shape #773 measures — a rule established where it was first noticed and never extended to its class. It is the same shape as #743, where a control defended the merge path while the push path stayed open, and as #767's record puts it: "'the ban is enforced' and 'the ban is enforced where it matters' were never separated." The generalisation is the fix; the six stripped instances in docs/defect-shapes-773.md were the symptom.

Why it leaks — a mechanism, not a discipline problem. A review finding creates pressure to answer in the artifact. The correction and the justification-for-the-correction get written in the same keystroke, and the artifact is the file already open, so the justification lands there too. Every one of the six instances came out of a review round. That is why the rule names a destination rather than only a prohibition: the commit message is written at the same moment, is permanent, and is where provenance is actually looked for.

Why the carve-out is half the rule. Over-stripping is the more common failure. A doc cut to bare facts reads as arbitrary and the next reader "fixes" it back — which is how a rejected approach gets re-proposed and a trap gets re-sprung. docs/defect-shapes-773.md carries both a dated measurement and a struck-through shellcheck row recording a tested negative result; both are reader-facing history and both must survive. The who-benefits test is what separates them from narrative, and it is stated as a question rather than a word list because a word list is exactly what the mechanised half of this cannot be trusted to be.

Why enforcement is advisory and stays that way. A narrative detector is a string predicate over prose. docs/defect-shapes-773.md §4 and testing.guard-derives-population-from-source both argue that a weak string-matching detector is the symptom-keyed mistake, and the withdrawn test_review_verdict_vocabulary_parity.py — six cold-review rounds, then deleted — is the empirical case: every round's fix was locally correct and the sequence never converged. As a blocking gate this is a bad bet. As a non-blocking nudge it is nearly free, and the repo already runs that exact pattern in docs-reminder for the parity doc. So the detector warns; it never fails a run. Budget for it being wrong sometimes, and make that acceptable by not letting it block.

It is Python, not shell, and that is the same argument one level down. A detector over diff output has to decide what each line IS, and deciding that from its prefix alone — without hunk state — is a string predicate too. Four distinct defects fell out of one bash implementation of it: the no-trailing-newline marker counted as content, an added line whose own text began ++ eaten by the +++ header arm, core.quotePath hiding non-ASCII paths, and a final unterminated line dropped by read. Those are four sites of one mistake, so the mechanism was replaced rather than the sites patched one at a time. Anything that parses a diff here should parse it with hunk state or not at all.

If this ever becomes a hook, it belongs at USER scope, not in this repo. The rule is not ersatztv-specific — it is true of every repo — and an ersatztv-only hook would enforce it exactly where it was first noticed and nowhere else, which is the shape this record exists to close. Mechanically that means ~/.claude/hooks/ plus the user settings.json. Worth stating because ~/.claude/hooks/ holds only cosmetic hooks today (terminal title, statusline), so there is no precedent there for a content rule and someone would have to decide that deliberately.