Generalize the no-session-narrative rule from the kickoff file to all docs — the reader never saw the earlier draft #784
Closed
opened 2026-08-13 20:54:00 +02:00 by timothy
·
4 comments
No Branch/Tag Specified
main
renovate/dotnet-monorepo
renovate/meziantou.analyzer-3.x
renovate/lucene.net
renovate/sqlitepclraw.bundle_e_sqlite3-3.x
renovate/cliwrap-3.x
913-scripted-playout-401
release/v26.15.0-notes
issue-806-guard-populations
scratch/767b-poisoned
scratch/767b-control
release/v26.14.0-notes
release/v26.14.0
docs/510-skill-logo-bug-policy
fix/510-watermark-resolution-policy
fix/629-verdict-classifier-falseopens
fix/609-decisions-edit-token-scope
issue-135-clear-to-none
release/v26.12.0-notes
fix/409b-lastscan-api-parity
fix/401-updatechannel-mirror-422
fix/327-playlist-rename-validation
fix/410-scancancel-log-level
fix/409-447-librariesscreen-neverscanned
fix/338-zap-exit-code
fix/367-plex-budget-message
fix/310-debom-legacy-cs
ci/604-lane-rebalance
feat/388-design-mirror
feat/247-test-ownership
feat/247-primary-action
feat/357-player-owned-playback
feat/357-jellyfin-plugin-poc
fix/289-mcp-hardening
issue58-mcp
feat/244-channels-extract
ci/auto-bump-prod-compose
feat/multi-rerun-collections-api
feat/collections-api
feat/quick-wins
feat/185-docs-part2
feat/140-collections-screen
feat/146-channel-edit
feat/147-classic-ui-link
issue22-renovate-dashboard
feat/91-cutover
feat/63-composite-create
feat/65-library-browse
feat/85-epg
feat/86-schedule-editor
feat/109-dashboard-data
feat/99-session-tracking
fix/dockerfile-node-tag
feat/59-spa-foundation
docs/59-ui-redesign-brief
feat/102-json-guide
feat/111-schedule-durations
feat/104-artwork-upload
feat/103-media-sources-api
feat/playouts-read-api
feat/108-health-api
feat/105-picker-list-endpoints
issue-97-channel-state-api
issue42-jellyfin-musicvideos
issue46-rest-api-error-contract
dependabot/nuget/ErsatzTV.FFmpeg.Tests/multi-d307a2e06f
qsv-improvements
hdr-vulkan-cuda-test
v26.16.0
v26.15.0
v26.14.0
v26.13.0
v26.12.0
v26.11.0
v26.10.0
v26.9.0
v26.8.0
v26.7.0
blazor-final
v26.6.0
v26.5.0
v26.4.0
v26.3.1
v26.3.0
v26.2.0
v26.1.1
v26.1.0
v25.9.0
v25.8.0
v25.7.1
v25.7.0
v25.6.0
v25.5.0
v25.4.0
v25.3.1
v25.3.0
v25.2.0
v25.1.0
v0.8.8-beta
v0.8.7-beta
v0.8.6-beta
v0.8.5-beta
v0.8.4-beta
v0.8.3-beta
v0.8.2-beta
v0.8.1-beta
v0.8.0-beta
v0.7.9-beta
v0.7.8-beta
v0.7.7-beta
v0.7.6-beta
v0.7.5-beta
v0.7.4-beta
v0.7.3-beta
v0.7.2-beta
v0.7.1-beta
v0.7.0-beta
v0.6.9-beta
v0.6.8-beta
v0.6.7-beta
v0.6.6-beta
v0.6.5-beta
v0.6.4-beta
v0.6.3-beta
v0.6.2-beta
v0.6.1-beta
v0.6.0-beta
v0.5.8-beta
v0.5.7-beta
v0.5.6-beta
v0.5.5-beta
v0.5.4-beta
v0.5.3-beta
v0.5.2-beta
v0.5.1-beta
v0.5.0-beta
v0.4.5-alpha
v0.4.4-alpha
v0.4.3-alpha
v0.4.2-alpha
v0.4.1-alpha
v0.4.0-alpha
v0.3.8-alpha
v0.3.7-alpha
develop
v0.3.6-alpha
v0.3.5-alpha
v0.3.4-alpha
v0.3.3-alpha
v0.3.2-alpha
v0.3.1-alpha
v0.3.0-alpha
v0.2.5-alpha
v0.2.4-alpha
v0.2.3-alpha
v0.2.2-alpha
v0.2.1-alpha
v0.2.0-alpha
v0.1.5-alpha
v0.1.4-alpha
v0.1.3-alpha
v0.1.2-alpha
v0.1.1-alpha
v0.1.0-alpha
v0.0.62-alpha
v0.0.61-alpha
v0.0.60-alpha
v0.0.59-alpha
v0.0.58-alpha
v0.0.57-alpha
v0.0.56-alpha
v0.0.55-alpha
v0.0.54-alpha
v0.0.53-alpha
v0.0.52-alpha
v0.0.51-alpha
v0.0.50-alpha
v0.0.49-prealpha
v0.0.48-prealpha
v0.0.47-prealpha
v0.0.46-prealpha
v0.0.45-prealpha
v0.0.44-prealpha
v0.0.43-prealpha
v0.0.42-prealpha
v0.0.41-prealpha
v0.0.40-prealpha
v0.0.39-prealpha
v0.0.38-prealpha
v0.0.37-prealpha
v0.0.36-prealpha
v0.0.35-prealpha
v0.0.34-prealpha
v0.0.33-prealpha
v0.0.32-prealpha
v0.0.31-prealpha
v0.0.30-prealpha
v0.0.29-prealpha
v0.0.28-prealpha
v0.0.27-prealpha
v0.0.26-prealpha
v0.0.25-prealpha
v0.0.24-prealpha
v0.0.23-prealpha
v0.0.22-prealpha
v0.0.21-prealpha
v0.0.20-prealpha
v0.0.19-prealpha
v0.0.18-prealpha
v0.0.17-prealpha
v0.0.16-prealpha
v0.0.15-prealpha
v0.0.14-prealpha
v0.0.13-prealpha
v0.0.12-prealpha
v0.0.11-prealpha
v0.0.10-prealpha
v0.0.9-prealpha
v0.0.8-prealpha
v0.0.7-prealpha
v0.0.6-prealpha
v0.0.5-prealpha
v0.0.4-prealpha
v0.0.3-prealpha
v0.0.2-prealpha
v0.0.1-prealpha
Labels
Clear labels
ad-hoc
api
bug
ci-cd
content
dependencies
enhancement
frontend
in-progress
jellyfin
parked
priority: high
priority: low
priority: medium
review
security
One-off / ad-hoc work not tracked by a dedicated issue
REST API / HTTP endpoints
Something isn't working
Build, test, deploy pipeline
Channel content / schedules / playlists
Dependency updates (Renovate)
New feature or improvement
ChicoryTV React SPA frontend
Claimed by an active session — do not pick up
Jellyfin tuner / IPTV integration
Excluded from automatic queue pickup; work only when explicitly selected
Adversarial review finding
Security / vulnerability fix
No labels
priority: medium
Milestone
No items
No Milestone
Defect-shape hardening
Projects
Clear projects
No projects
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: timothy/ersatztv#784
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Spawned by #773. Found while writing
docs/defect-shapes-773.md, which had accumulated six places narrating its own revision history ("an earlier draft counted...", "the first version of this table said 18", "my first attempt returned 0 forBashtoo"). All six were stripped in that PR; this issue is about the boundary, not those sites.The rule already exists, scoped to one file
docs/handoffs/chicorytv-issue-queue.mdsays it, correctly:That reason is file-specific (this file is pasted every session). The general reason is different and broader: a reader coming to any doc cold never saw the earlier draft, so "we previously got this wrong" carries no information 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. Same as #743 (a control that defended the merge path while the push path stayed open) and as #767's own record puts it: "'the ban is enforced' and 'the ban is enforced where it matters' were never separated."
Why it leaks (mechanism, not sites)
A review finding creates pressure to answer in the artifact. The correction and the justification-for-the-correction are 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.
Proposed rule
A review finding is answered in the commit message; only the corrected claim enters the doc. The commit is written at the same moment, is permanent, and is where provenance is actually looked for. Per-issue narrative belongs in the
## Closing record.Stating the destination is load-bearing: "don't write it in the doc" without a home loses the knowledge, and this repo has the inverse failure on record too (pruning a narrative that turned out to be the only copy — #542).
The carve-out, which must be explicit or the rule gets over-applied
History that is reader-facing and must survive:
supersedes/superseded-bydocs/defect-shapes-773.mdcarries both)shellcheckrow, which exists so nobody re-proposes it on plausibilityThe test is who benefits. If only the author's timeline explains why the sentence is there, it is narrative. If a reader would act differently knowing it, it is a finding.
On mechanising it — advisory only, and #773 §3.7 says why
A grep over added lines in
docs/**forearlier draft|first version|previously said|used to say|we were wrongis a string predicate.#773§3.7 andci.*precedent say those need 3+ rounds and fail in unanticipated ways, so as a blocking gate it is a bad bet. As a non-blocking nudge it is nearly free, and the repo already has that exact pattern in thedocs-reminderjob.So: extend
docs-reminder, do not add a gate.Done-when
docs.no-session-narrative)docs-reminderextended with the advisory check, explicitly non-blocking, with its false-positive behaviour on the carved-out cases checked againstdocs/defect-shapes-773.md(which deliberately contains legitimate history and must not be flagged into deletion)docs/*.mdfor the same leak, reporting what it found rather than assuming this document was the only offenderScope note (from a #776 session, 2026-08-14): if this ever becomes a hook, it belongs at USER scope, not in this repo. The rule — a reader coming to any doc cold never saw the earlier draft — 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 very shape this issue is about.
Mechanically that means
~/.claude/hooks/+ the usersettings.json, not.claude/hooks/here. Worth stating because~/.claude/hooks/currently holds only cosmetic hooks (terminal title, statusline) — there is no precedent there for a content rule, so someone would have to decide that deliberately.Two caveats that should survive into whatever gets built:
docs/defect-shapes-773.md§4 argues against weak string-matching detectors —testing.guard-derives-population-from-sourcecalls a weak detector the symptom-keyed mistake, and the withdrawntest_review_verdict_vocabulary_parity.py(six rounds, then deleted) is the empirical case. So this is plausible as an advisory PostToolUse reminder on doc writes, and not plausible as a blocking guard. Budget for it being wrong sometimes, and make that acceptable by not letting it block.docs/decisions/records/**narrate how a rule was got wrong on purpose — that IS the rationale a record exists to carry (seetesting.guard-ships-with-mutation-proof, which recounts failing its own rule three times). A detector that does not exempt them would fight the convention it is meant to serve.Claiming this (Claude Code session, 2026-08-21). Checked first: no open PR references #784, no remote branch names it, and the only prior comment is the '#776 scope note', not a claim.
Plan: decision record
docs.no-session-narrative(who-benefits test + carve-out), point the kickoff file's file-specific wording at it, extend the non-blockingdocs-reminderjob with the advisory check (verified againstdocs/defect-shapes-773.mdand exemptingdocs/decisions/records/**), and sweepdocs/*.mdreporting what it finds.Sweep report (Done-when box 4) — reporting, not remediating
Two independent passes over the tracked docs corpus at
706674272, excludingdocs/decisions/**(exempt by the rule):scripts/check-doc-narrative.sh --all, the advisory string predicate this PR adds — 10 sitesUnion 21 sites across 6 files. Each pass missed sites the other caught: the detector's phrase list has no entry for "the first draft called that", "this row previously said", or "this paragraph used to describe", all of which the reading pass found; the reading pass stopped at its 25-file cap and missed three the detector caught. That divergence is the measured argument for keeping the check advisory rather than a gate — it is the same shape as the withdrawn
test_review_verdict_vocabulary_parity.py, arrived at by measurement instead of by six review rounds.Every cited line was re-read in the file rather than taken from a summary. Full table and per-file breakdown: #812, which is the remediation issue.
This document was not the only offender —
docs/ci-cd.md(6),docs/remote-state-inventory.md(7) anddocs/guard-inventory.md(4) each carry more thandocs/defect-shapes-773.mddoes now (1).Remediation is deliberately NOT in this PR. A material fraction of the 21 pass the who-benefits test and must stay — the
remote-state-inventorycluster is largely "this row was graded down by cold review and the earlier wording was circular", which exists to stop the next reader regrading it back. That is 21 individual judgements, and #542 is this repo's record of pruning a narrative that turned out to be the only copy. Batching them behind the rule that authorized them is the failure mode the rule's own carve-out warns about.False-positive check against
docs/defect-shapes-773.mdThe issue asked specifically whether the check would flag that file's legitimate history into deletion. It does not:
shellcheckrow (a tested negative result): not flagged"…and an earlier draft of this paragraph quietly contradicted it"— a genuine hit, correctly identifiedAnd in CI the check scans only lines added in the PR diff, so the existing corpus of legitimate history is structurally out of its reach.
docs/decisions/**is exempt wholesale in both modes.Closing record
Outcome: Shipped in PR #811 (squash-merged as one commit on
main). The rule is generalized fromdocs/handoffs/chicorytv-issue-queue.mdto every durable artifact, with a named destination and an explicit carve-out:docs/decisions/records/docs/no-session-narrative.md(docs.no-session-narrative). The kickoff file now cites the general rule and keeps only its extra file-specific cost.scripts/check-doc-narrative.pyruns as a second, non-blocking step indocs-reminder.Root cause: Not a bug — the shape #773 measures. The rule was established where it was first noticed (a file pasted into every session, whose file-specific reason was "narrative here taxes every future session") and never extended to its class. The general reason is different and broader: a reader coming to any doc cold never saw the earlier draft. Same shape as #743 and #767.
Decisions/conventions changed: Added
docs.no-session-narrative. Nothing superseded.Reusable knowledge:
git diffoutput is a string predicate too, one level down. Deciding what a diff line IS from its prefix, without hunk state, produced four defects in one bash implementation (the no-newline marker as content; an added line whose text began++eaten by the+++arm;core.quotePathhiding non-ASCII paths;readdropping a final unterminated line). Four sites, one mistake. Replacing the mechanism converged; patching the sites would not have.scanned 0 file(s)—core.quotePath, thendiff.dstPrefix, thencolor.diff/color.ui. Pinning the third one would have been a fourth variant patch. What closed it: remove the surface (GIT_CONFIG_GLOBAL/SYSTEM/NOSYSTEM→ devnull), pin each named knob on the command line where it also beats a repo-local config, and put every demonstrated knob in aFORMAT_KNOBStable so the next one found becomes a row instead of a round. An independent 46-configuration matrix then found zero false cleans.grep -cfor hit-counting, andgit diff -U0hunk headers give correct new-file line numbers if and only if you track hunk state.Verification:
scripts/tests/807 passed, 2 skipped. Newscripts/tests/test_check_doc_narrative.py(36 tests) with aPATTERNSmutation proof, and every load-bearing clause disarmed and witnessed red.prove-fixreports PROVEN for a behaviour reason. Positive control for--diff(a narrative line in a doc, in a decision record, and in the script → only the doc flagged, correct line number, exit 0) and negative control (this PR's own diff → nothing to flag). CI green ond938493d5; the new step's execution confirmed in the real job log (doc-narrative: scanned 5 file(s)) rather than inferred from a green job.ruff checkclean.Deferred: Remediation of the 21 existing sites the sweep found — #812. They are 21 individual who-benefits judgements, not a regex: a material fraction (the
docs/remote-state-inventory.mdcluster especially) are load-bearing findings that must stay. Also deferred, and recorded in the record rather than implied covered: the error/degradation arms (git()'sOSErrorreturn,run_all's sentinel,open(errors=), the top-levelexcept,-U0,--src-prefix, the env overrides) are defensive and unproven by design.Docs updated:
docs/decisions/records/docs/no-session-narrative.md(new),docs/decisions/README.md(regenerated),docs/README.md(task-signal row),docs/ci-cd.md(docs-remindernow documents both steps),docs/handoffs/chicorytv-issue-queue.md,docs/guard-inventory.md(TOOLING + PROOF rows, counts),docs/remote-state-inventory.md(N/Arow).Review: eight cold rounds in isolated worktrees. Rounds 1–5 returned BLOCKED and each was right; the last three verdicts were MERGEABLE. Two findings were ones I had reached independently (the colour knob, and two of my own tests being vacuous), which is the useful signal — the rest I would not have found.