Skip to content

Remove docs that go stale when code changes - #76

Merged
moshez merged 1 commit into
mainfrom
w70-docs
Nov 10, 2026
Merged

moshez merged 1 commit into
mainfrom
w70-docs

Conversation

@moshez

@moshez moshez commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Fixes #70

Head: 7c34362

Plan

Done-when (word for word): the "CI is pinned" section of CLAUDE.md is removed, or replaced by one line pointing to repository-prototype's CLAUDE.md ("A library's check.yml is a caller of package-check.yml" and "CI Pattern: every input is pinned"); any passage of CLAUDE.md or README.md that restates what the code does (a list of functions, their signatures, a command's flags or output) is removed or replaced by a pointer to the package's generated docs or to the command's help text; sections that state a decision, its research, or what is proved apart from what is tested stay; a comment in the PR lists each section of CLAUDE.md and README.md and what became of it (kept as a decision, pointer, removed). If this repository's CI or tests read the removed text (grep before removing), that is changed in the same PR.

  1. git diff --stat origin/main HEAD: only CLAUDE.md and README.md change, mostly deletions (the one added line is the pointer that replaces "CI is pinned").
  2. grep -rn "CI is pinned" --exclude-dir=.git .: no match, so nothing in CI or tests reads the removed text (exit status 1).
  3. CI pointer: workflow check.yml, job check / check, step bats check; the log of the run for the head shows the line check / check as passed (the run is found with gh api repos/bats-lang/argparse/actions/runs?head_sha=<head>); a draft pull request runs no job, so that run appears after the orchestrator marks it ready.

The comment listing each section and what became of it is posted on this PR.

Execution

Replaced the "CI is pinned" section of CLAUDE.md by one pointer line to repository-prototype's CLAUDE.md. In README.md removed "Features" and "Usage" (they restate the API and the error constructors) and kept the "API" pointer to docs/lib.md and the "Safety" section (a statement of what is proved).

Deviations: none

Evidence

$ git diff --stat origin/main HEAD
 CLAUDE.md | 29 +----------------------------
 README.md | 26 --------------------------
 2 files changed, 1 insertion(+), 54 deletions(-)
$ grep -rn "CI is pinned" --exclude-dir=.git .
exit status: 1

Generated by Claude Code

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HwLsLtFgHv4ix6TZzPYRcT

moshez commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

Sections of CLAUDE.md and README.md and what became of each:

  • CLAUDE.md, "CI is pinned": removed, replaced by one line pointing to repository-prototype's CLAUDE.md ("A library's check.yml is a caller of package-check.yml" and "CI Pattern: every input is pinned"). Pointer.
  • README.md, intro line: kept (what the package is).
  • README.md, "Features": removed (restates what the code does).
  • README.md, "Usage": removed (function signatures and error constructors; the code and docs/lib.md are the authority).
  • README.md, "API": kept as a pointer to the generated docs/lib.md.
  • README.md, "Safety": kept as a decision (what is proved: every table access is in bounds by the types).

Grep before removing: nothing in CI or tests reads "CI is pinned".

Generated by Claude Code


Generated by Claude Code

@moshez
moshez marked this pull request as ready for review November 10, 2026 11:34

moshez commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

Independent review (a separate reviewer agent, not the author) of head 7c34362: approved, no blocking findings
Plan quotes the Done-when word for word and its checks are runnable; Execution matches the diff (two files, 1 insertion, 54 deletions). At this head check / check and check / layout passed, check / c-runtime was skipped, and the text-lint status is success.
Done-when: the CI-is-pinned section of CLAUDE.md is replaced by one pointer line naming both repository-prototype sections. In README.md the removed "Features" and "Usage" restate the API, signatures and error constructors; the intro, the "API" pointer to docs/lib.md and "Safety" (what is proved) stay. The only added line in any .md is the pointer line. The section-by-section comment lists every section of both files and what became of each. The grep for the removed heading finds nothing, so nothing reads the removed text.
NOTE: the section-by-section comment ends with two footer lines; the PR body, which is what the body form covers, has exactly one footer, no session URL, and a Head line equal to the head.
Verdict: approved


Generated by Claude Code

moshez commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

Independent review (a separate reviewer agent, not the author) of head 7c34362: approved, no blocking findings
Plan quotes the Done-when word for word and its checks are runnable; Execution matches the diff (two files, 1 insertion, 54 deletions). At this head check / check and check / layout passed, check / c-runtime was skipped, and the text-lint status is success.
Done-when: the CI-is-pinned section of CLAUDE.md is replaced by one pointer line naming both repository-prototype sections. In README.md the removed "Features" and "Usage" restate the API, signatures and error constructors; the intro, the "API" pointer to docs/lib.md and "Safety" (what is proved) stay. The only added line in any .md is the pointer line. The section-by-section comment lists every section of both files and what became of each. The grep for the removed heading finds nothing, so nothing reads the removed text.
NOTE: the section-by-section comment ends with two footer lines; the PR body, which is what the body form covers, has exactly one footer, no session URL, and a Head line equal to the head.
Verdict: approved
Body: 03de43a8c31c2212


Generated by Claude Code

@moshez
moshez merged commit c9ded49 into main Nov 10, 2026
10 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove docs that go stale when code changes

2 participants