chore(docs): trim derivable content from CLAUDE.md, lazy-load the task-completion protocol #588

2026-07-25T11:23:37+02:00

timothy commented

2026-07-25 11:23:37 +02:00

fixes #587

Docs-only. Two files: CLAUDE.md and a new .claude/skills/closing-an-issue/SKILL.md.

Cut from CLAUDE.md — reconstructible from the repo: the ### Project Layout table, the dotnet build / dotnet run invocations (the non-obvious docker build -f docker/Dockerfile … line stays), and the Language / Media / Functional C# bullets that the csproj files and Directory.Packages.props already state.

Migrated to lazy loading: the 7 mandatory completion steps and the ## Closing record template now live in .claude/skills/closing-an-issue/SKILL.md, so only its one-line description stays resident. /done and the skill both reach the same content.

Kept on purpose: the entire ## Done-when / merge-consent block stays in CLAUDE.md — it is safety-critical and describes hook behaviour that fires regardless of whether a skill was loaded. Also kept: ### Key Files, the UI/Blazor-removal history, ## Conventions, ## Project Boundaries.

13,306 → 10,801 chars, ~625 est. tokens off every session's startup context.

No convention, route, /api/* endpoint, or decision changed, so the docs-update table triggers no other doc edits.

🤖 Generated with Claude Code

fixes #587 Docs-only. Two files: `CLAUDE.md` and a new `.claude/skills/closing-an-issue/SKILL.md`. **Cut from `CLAUDE.md` — reconstructible from the repo:** the `### Project Layout` table, the `dotnet build` / `dotnet run` invocations (the non-obvious `docker build -f docker/Dockerfile …` line stays), and the Language / Media / Functional C# bullets that the csproj files and `Directory.Packages.props` already state. **Migrated to lazy loading:** the 7 mandatory completion steps and the `## Closing record` template now live in `.claude/skills/closing-an-issue/SKILL.md`, so only its one-line description stays resident. `/done` and the skill both reach the same content. **Kept on purpose:** the entire `## Done-when` / merge-consent block stays in `CLAUDE.md` — it is safety-critical and describes hook behaviour that fires regardless of whether a skill was loaded. Also kept: `### Key Files`, the UI/Blazor-removal history, `## Conventions`, `## Project Boundaries`. 13,306 → 10,801 chars, ~625 est. tokens off every session's startup context. No convention, route, `/api/*` endpoint, or decision changed, so the `docs-update` table triggers no other doc edits. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

timothy added 1 commit 2026-07-25 11:23:37 +02:00

chore(docs): trim derivable content from CLAUDE.md, lazy-load the task-completion protocol

PR Gates / CI image pin matches docker/ci (pull_request) Successful in 11s

Details

PR Gates / Docs update reminder (pull_request) Successful in 16s

Details

PR Gates / decisions lifecycle (pull_request) Successful in 16s

Details

Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 17s

Details

Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 30s

Details

Build ErsatzTV Image / Functional E2E (curl contracts) (pull_request) Successful in 20s

Details

Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 20s

Details

Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 20s

Details

Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped

Details

e678e6653e

Session context/config checkup (/doctor) found ~2.5k chars of always-loaded
CLAUDE.md text that a session can reconstruct from the codebase, plus a
task-specific workflow that only matters when closing an issue.

Cut (derivable from the repo):
- the `### Project Layout` table (what `ls` shows)
- the `dotnet build` / `dotnet run` invocations (standard for the toolchain;
  the non-obvious `docker build -f docker/Dockerfile` line is kept)
- the Language / Media / Functional C# bullets (stated by the csproj and
  Directory.Packages.props)

Migrated to lazy loading:
- the 7 mandatory completion steps and the `## Closing record` template move
  to .claude/skills/closing-an-issue/SKILL.md; only its one-line description
  stays resident. The `## Done-when` / merge-consent block stays in CLAUDE.md
  on purpose — it is safety-critical and describes hook behaviour that fires
  whether or not a skill was loaded.

CLAUDE.md 13,306 -> 10,801 chars (~625 est. tokens saved per session).
No convention, route, endpoint or decision changes, so no other doc updates
are triggered by the docs-update table.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

timothy commented

2026-07-25 12:24:57 +02:00

Cold review of the full diff at head e678e665.

Checked — reference integrity. The risk in this diff is a dangling pointer: seven places outside CLAUDE.md cite "CLAUDE.md → Task Completion Protocol" (docs/README.md, docs/decisions/release-ci-governance.md ×3, docs/handoffs/chicorytv-issue-queue.md, docs/handoffs/rest-api.md, and the ask message in .claude/hooks/pretooluse-merge-consent.sh). The ## Task Completion Protocol heading is retained — only its 7-step body moved — so every one of those still resolves to a real section, which now carries the merge-consent block plus an explicit pointer to the skill. Verified against the branch, not assumed.

Checked — nothing safety-critical moved. The entire ## Done-when / H6 / H10 merge-consent block stays resident in CLAUDE.md. It describes hook behaviour that fires whether or not a skill was loaded, so moving it into a lazily-loaded skill would have been the one genuinely unsafe edit here. It wasn't made.

Checked — the cuts are actually derivable. Project layout is ls; dotnet build ErsatzTV.sln / dotnet run --project ErsatzTV are the standard invocations; .NET 10 / CliWrap / SkiaSharp / LanguageExt are all stated by the csproj files and Directory.Packages.props. The non-obvious docker build -f docker/Dockerfile … line was kept, as were ### Key Files, the Blazor-removal history, ## Conventions, and ## Project Boundaries.

Minor, accepted: docs/decisions.md and two handoff docs reference the ## Closing record template, which now lives in the skill rather than inline in CLAUDE.md. The retained pointer line makes it findable, and the skill's description matches on "closing record", so no doc edit is warranted.

Not re-litigated: whether this content belonged in CLAUDE.md at all. It's a judgment call the repo owner made and confirmed.

CI: all 8 jobs green, image push correctly skipped for a docs-only change.

Review-verdict: MERGEABLE @ e678e6653e

Cold review of the full diff at head `e678e665`. **Checked — reference integrity.** The risk in this diff is a dangling pointer: seven places outside `CLAUDE.md` cite "CLAUDE.md → Task Completion Protocol" (`docs/README.md`, `docs/decisions/release-ci-governance.md` ×3, `docs/handoffs/chicorytv-issue-queue.md`, `docs/handoffs/rest-api.md`, and the `ask` message in `.claude/hooks/pretooluse-merge-consent.sh`). The `## Task Completion Protocol` heading is retained — only its 7-step body moved — so every one of those still resolves to a real section, which now carries the merge-consent block plus an explicit pointer to the skill. Verified against the branch, not assumed. **Checked — nothing safety-critical moved.** The entire `## Done-when` / H6 / H10 merge-consent block stays resident in `CLAUDE.md`. It describes hook behaviour that fires whether or not a skill was loaded, so moving it into a lazily-loaded skill would have been the one genuinely unsafe edit here. It wasn't made. **Checked — the cuts are actually derivable.** Project layout is `ls`; `dotnet build ErsatzTV.sln` / `dotnet run --project ErsatzTV` are the standard invocations; .NET 10 / CliWrap / SkiaSharp / LanguageExt are all stated by the csproj files and `Directory.Packages.props`. The non-obvious `docker build -f docker/Dockerfile …` line was kept, as were `### Key Files`, the Blazor-removal history, `## Conventions`, and `## Project Boundaries`. **Minor, accepted:** `docs/decisions.md` and two handoff docs reference the `## Closing record` template, which now lives in the skill rather than inline in `CLAUDE.md`. The retained pointer line makes it findable, and the skill's description matches on "closing record", so no doc edit is warranted. **Not re-litigated:** whether this content belonged in `CLAUDE.md` at all. It's a judgment call the repo owner made and confirmed. CI: all 8 jobs green, image push correctly skipped for a docs-only change. Review-verdict: MERGEABLE @ e678e6653ebdc440d9718e8d31e0440f3113ce17

timothy referenced this pull request

2026-07-25 12:25:14 +02:00

chore(docs): trim derivable content from CLAUDE.md and lazy-load the task-completion protocol #587

timothy merged commit 0952078c2b into main

2026-07-25 12:25:21 +02:00

timothy deleted branch chore/claudemd-trim-lazy-skill

2026-07-25 12:25:22 +02:00

timothy referenced this issue from a commit

2026-07-25 12:25:22 +02:00

Merge pull request 'chore(docs): trim derivable content from CLAUDE.md, lazy-load the task-completion protocol' (#588) from chore/claudemd-trim-lazy-skill into main

timothy referenced this pull request

2026-07-25 12:26:10 +02:00