[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72XMJMCS4NS3YAZ8FXDSXTS":3,"skill-same:01M72XMJMCS4NS3YAZ8FXDSXTS":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":32,"ownerHtmlUrl":33,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":34,"install":35,"resources":48},"01M72XMJMCS4NS3YAZ8FXDSXTS","code-docs-cleanup",null,"Clause-by-clause procedure for shortening and cleaning up source-code comments without losing a guard, the comment that says why a non-obvious line must stay as it is and what breaks if it changes. Use when someone asks to shorten, trim or clean up comments, says a file has too many or overly verbose comments or is over-commented, cut comment density or comment bloat, split an essay comment or an over-long doc comment or docstring, move design rationale out of code into a decision record, remove plan, work-package, review-round or decision IDs from comments, delete comments that restate the code, bring a file under the code-docs length caps, or prepare a file or package for the code-docs comment ratchet. Not for writing the comment standards, which the code-docs rule carries, not for --help, JSON Schema, MCP tool descriptions or other text that renders to users, and not for user-facing documentation pages, which the docs-quality rules cover.","grimoire-rs\u002Fgrimoire","grimoire-rs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F298895348?v=4","01M72XK7XKYKMET2MMHCAQ3X6C","01M72XK7Y647QCPS3Z02ZYTJTT",15,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcode-docs-cleanup\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: code-docs-cleanup\ndescription: Clause-by-clause procedure for shortening and cleaning up source-code comments without losing a guard, the comment that says why a non-obvious line must stay as it is and what breaks if it changes. Use when someone asks to shorten, trim or clean up comments, says a file has too many or overly verbose comments or is over-commented, cut comment density or comment bloat, split an essay comment or an over-long doc comment or docstring, move design rationale out of code into a decision record, remove plan, work-package, review-round or decision IDs from comments, delete comments that restate the code, bring a file under the code-docs length caps, or prepare a file or package for the code-docs comment ratchet. Not for writing the comment standards, which the code-docs rule carries, not for --help, JSON Schema, MCP tool descriptions or other text that renders to users, and not for user-facing documentation pages, which the docs-quality rules cover.\nlicense: Apache-2.0\nmetadata:\n  summary: Shortens comments clause by clause, guard first, gated by a structural diff check and a cold reason re-check for every shortened guard\n  keywords: comments,code-comments,comment-cleanup,comment-density,doc-comments,docstrings,rustdoc,jsdoc,tsdoc,godoc,javadoc,kdoc,guards,why-comments,essay-comments,decision-records,adr,plan-ids,process-ids,pointers,ratchet,length-caps,refactor,code-docs\n  repository: https:\u002F\u002Fgithub.com\u002Focx-sh\u002Fgrimoire-lore\n---\n\n# code-docs-cleanup\n\nShorten the comments in a source file without losing a guard. A guard is any\nclause that names a constraint a plausible edit would break, with or without the\nconsequence. It is how the next agent learns why a non-obvious line looks the way\nit does and whether it may change it.\n\nThe comment standards live in the installed `code-docs` rule, cited here by\nID: GRD (guards), RTE (routing), LNK (pointers and IDs), SRF (rendered\nsurfaces) and LEN (length and ratchet). The cleanup-safety rules, CLN, are this\nskill's own: [Cleanup rules](#cleanup-rules). Three facts shape every step (as\nof 2026-09):\n\n- In agent-written code most comment lines are guards and contracts, not essays.\n  Deleting by category or by length deletes guards.\n- The shipped guard recogniser finds fewer than half of real guards (recall\n  about 0.43). A block it does not flag is unclassified, never safe to cut.\n- The editing agent's belief that the meaning survived is not evidence. The\n  structural check and a cold re-check are.\n\nContents: [When to run](#when-to-run) · [Setup](#setup) · [Scope](#scope) ·\n[Procedure](#procedure) · [Never touch](#never-touch) · [Cleanup rules](#cleanup-rules) · [Report](#report) ·\n[MUST rows](#must-rows-this-procedure-surfaces) ·\n[What agents get wrong](#what-agents-get-wrong) · [References](#references)\n\n## When to run\n\nRun it when:\n\n- A change already edits a file whose comments are over the length caps\n  (LEN-01, LEN-02), carry bare process IDs (LNK-01), or hold an essay.\n- The owner names files for a sweep, or asks to bring a package down before its\n  ratchet baseline is recorded (LEN-03).\n- A review flags an over-cap block, or a pointer left beside the essay it was\n  meant to replace (RTE-09).\n\nDo not run it when:\n\n- The text renders to users: `--help`, JSON Schema, MCP tool descriptions,\n  argparse or commander help, or a published package's API docs. That is an\n  interface change (SRF-01, SRF-02). It moves rationale into plain comments and\n  may regenerate goldens, which this skill never does.\n- The file is a test, generated, vendored, a lock or manifest file, or a golden.\n  Bare IDs in test files and test regions (LNK-01's `bare-id-test` key) go in a\n  separate test-only change: list them in the report.\n- Another branch has the file in flight (see [Scope](#scope)).\n- The fix is code: a type that owns a guard (GRD-12), a lint to enable (GRD-09,\n  GRD-10), a test to rename. Each is its own reviewable diff.\n- The repo's own rules protect the comment kind, for example a local rule that\n  keeps section dividers or phase markers. The local rule wins until it is\n  amended. Leave those comments and report the conflict.\n\n## Setup\n\n1. Find the rule's checks, in the project first, then in the global client\n   directories:\n   `find . \"$HOME\u002F.claude\" \"$HOME\u002F.config\" -path '*\u002Fcode-docs\u002Fchecks\u002Fcleanup_check.py' -not -path '*\u002Fnode_modules\u002F*' 2>\u002Fdev\u002Fnull | head -n 1`.\n   `CHECKS` below is the directory of that hit; any installed copy works. Read\n   the `code-docs.md` index installed beside the `code-docs\u002F` folder. No hit\n   means the rule is installed neither in the project nor globally: install it\n   with `grim add ghcr.io\u002Focx-sh\u002Flore\u002Fcode-docs`. Where the client tool cannot\n   install it, copy `code-docs.md` and the `code-docs\u002F` folder from the rule's\n   source into the client's rules directory (such as `.claude\u002Frules\u002F`) with\n   `rsync -a --exclude __pycache__` or `git archive`, so no stale `.pyc` file\n   rides along, commit that on its own before the cleanup, and run the find\n   again.\n2. `python3 \"$CHECKS\u002Fcleanup_check.py\" --self-test` and\n   `python3 \"$CHECKS\u002Fguard_recogniser.py\" --self-test` both exit 0.\n3. `git status --porcelain` lists nothing untracked that the cleanup did not\n   create. `cleanup_check.py` reads every untracked file as an added path and\n   fails it (CLN-05). An untracked file you did not create is the owner's: never\n   delete or revert it. Run the cleanup from a clean worktree, or ask the owner\n   to move the file.\n4. Pick the mode and set `BASE=HEAD`. The check fails any non-prose line that\n   differs from the base, so the working tree holds only uncommitted cleanup:\n   the touched files', or in a sweep one file's.\n\n| Mode | When | Before each file |\n|---|---|---|\n| Touched files (default) | Cleaning files the current change already edits | Commit the change's code first |\n| Sweep | The owner named files, or asked for a package sweep | Commit the previous file's cleanup, on a branch made for the sweep from the default branch |\n\n5. Declare every library-kind package in `.code-docs.json` before ranking or\n   cleaning anything: `python3 \"$CHECKS\u002Fcomment_census.py\" --root . --report`\n   lists undeclared packages that look published. The caps, and so the scope\n   of the sweep, depend on the declaration.\n\nCaps are the rule's defaults: plain blocks 5 lines, doc blocks 10, or 15 for a\npublic item in a library-kind package. The census reads them, and the list of\nlibrary packages, from `.code-docs.json` at the repo root. An adopter may\noverride both there, and list under `interface_files` the sources a generator\nthe checks do not know renders, such as a TS-to-JSON-Schema script. Their doc\ncomments are then frozen like clap's.\n\n## Scope\n\n- **Touched files:** only the files the change already edits (CLN-08). Never\n  widen to a neighbour because it looks worse.\n- **Sweep:** one file per commit (CLN-08). Rank packages with\n  `python3 \"$CHECKS\u002Fcomment_census.py\" --root . --report` and files with\n  `--over-cap`. Before starting a file, and again before merge, skip it if either\n  command prints anything:\n\n```\nFILE=src\u002Fexample.rs; MAIN=origin\u002Fmain; SELF=$(git branch --show-current)\ngit worktree list --porcelain | grep -e '^branch' | cut -d\u002F -f3- | grep -v -x -F -e \"$SELF\" | xargs -r -I{} git log -1 --format='{} %h %cs' \"$MAIN..{}\" -- \"$FILE\" || echo \"in-flight check unavailable\"\nFILE=src\u002Fexample.rs gh pr list --state open --limit 100 --json headRefName,files --jq '.[] | select(any(.files[]; .path == env.FILE)) | .headRefName' || echo \"in-flight check unavailable\"\n```\n\nThe first names a worktree branch with commits on the file, the second an open\npull request that edits it. Commit age settles nothing: a branch idle for a\nweek still merges. `in-flight check unavailable` means unknown, never clear:\nlist the file as unchecked in the report and have the owner confirm it before\nmerge.\n\n## Procedure\n\nWork one file at a time, one block at a time, top to bottom. Steps 1 to 3 read\nand classify every block. Steps 3 to 7 edit prose only, and only in over-cap\nblocks, blocks with a bare ID, and guards that fail GRD-01 or GRD-05. Every\nother block stays byte-identical. Steps 8 to 10 prove the edit.\n\n### 1. List the blocks\n\n```\nFILE=src\u002Fexample.rs\npython3 \"$CHECKS\u002Fcomment_census.py\" --root . --over-cap | grep -F -e \"$FILE:\"\npython3 \"$CHECKS\u002Fguard_recogniser.py\" --root . | grep -F -e \"$FILE:\"\npython3 \"$CHECKS\u002Flinkage_check.py\" ids --root . | grep -F -e \"$FILE:\"\npython3 \"$CHECKS\u002Flinkage_check.py\" pointers --root . | grep -F -e \"$FILE:\"\ngit grep -n -F -e \"${FILE##*\u002F}\" -- . \":(exclude)$FILE\" ':(exclude)*.md'\nMODULE=example; DOTTED=package.example   # the module without its extension, and its Python dotted path\ngit grep -n -F -e \"$MODULE.js\" -e \"$MODULE'\" -e \"$DOTTED\" -- . \":(exclude)$FILE\" ':(exclude)*.md'\ngit grep -n -F -e \"::: $DOTTED\" -e \"automodule:: $DOTTED\" -- .\n```\n\nThe first four rank the work. They do not bound it: every comment block in the\nfile goes through step 3, flagged or not. The rest find every reader, under\nevery name it can use: the path (a script, task file, CI config or test), the\nmodule name without its extension (a TS\u002FJS import ending in `.js`), the Python\ndotted module path, and a doc-generator directive (mkdocstrings `::: pkg.module`,\nSphinx `automodule::`). Never exclude `*.md` from the directive search: a hit\nthere means the module's docstrings render into published docs, so treat them\nas interface text (CLN-03). Read every hit; a name can match an unrelated file\n(`_rest.py` also matches `01_shellcheck_rest.py`). One that reads the file owns\nits comment text: text a check asserts stays verbatim. Record each in the\nworklist.\n\n### 2. Record every guard before you edit\n\nWrite a worklist in a scratch directory outside the repo. One row per guard\nclause: the line it guards, the constraint, the breaking edit, the consequence,\nand any owner the text claims (a test, a lint, a type). When unsure whether a\nclause is a guard, it is one.\n\nThe worklist feeds steps 5, 8 and 9. It is never an input to the check, which\nderives everything from the diff so that the editing agent never writes its own\ngrading input (CLN-04).\n\n### 3. Classify clause by clause, guard first\n\nSplit every block into clauses and tag each with\n[references\u002Fdecision-list.md](references\u002Fdecision-list.md) (RTE-01). Check for a\nguard before anything else.\n\n- Delete a clause outright only when the list positively identifies it as\n  narration, tautology, a banner, a bare ID or unquantified pure provenance\n  (CLN-01). Argument and record paraphrase leave only through step 6.\n- Length, a history phrase or a `Step N:` opener identifies nothing.\n- A block the recogniser flags, a `SAFETY:` label, the repo's deferred-shortcut\n  marker (for example `ponytail:`) and a comment another rule mandates (a\n  discard rationale, a lint-suppression reason) are never deleted whole (GRD-06).\n- Text a repo check asserts (step 1) stays verbatim.\n- A clause that fits no row stays.\n\n### 4. Rewrite each guard as fact plus consequence, at its line\n\n- Keep the constraint and the concrete consequence of breaking it. No edit goes\n  below that floor (GRD-01). \"Important\", \"careful\" or \"load-bearing\" alone is\n  not a consequence.\n- Keep nothing else in the guard: no history, no weighed alternatives, no bare\n  ID. Name the tempting edit only when the constraint does not imply it, and\n  name the sibling the code must not be unified with when that is the risk\n  (GRD-02).\n- Split a guard block over 5 lines clause by clause. Every breaking edit the\n  original forbade keeps its own sentence, at the line it guards. Never\n  paraphrase several guards into one line (CLN-02, LEN-05). State each guard\n  once (GRD-03).\n- Phrase it as a present-tense fact, never a command to the reader (GRD-05).\n  History that still constrains an edit becomes a present-tense guard (RTE-11).\n- Put a caller-visible precondition in the doc comment and an implementation\n  hazard in a plain comment at its line (GRD-04). Add no marker prefix.\n  `SAFETY:` stays where the language uses it.\n- When the guard clauses alone exceed the cap, keep them all and tighten the\n  wording. The cap never drops a guard.\n- Rewrite a clause as you move it. The check fails prose the recogniser does\n  not flag that reappears, 80% or more intact, elsewhere in the same file\n  (CLN-04).\n- Never invent a consequence the original does not state and the code does not\n  show. Keep the original wording and list the block in the report.\n\n### 5. Shrink a guard to its owner only after a planted edit fails it\n\nA guard shrinks to a one-line pointer only when every breaking edit it names\nhas a proven owner (CLN-07, GRD-07, RTE-03). An owner is an enabled lint, a\nscoped `deny`, a type check, or any test, named in the block or not. It is\nproven only when it passes on the unmodified scratch copy and fails on that\nexact edit applied to the same copy: a test already red before the edit proves\nnothing. Run the suite on the planted edit to find the candidates, then each\nred test alone:\n\n```\nSCRATCH=$(mktemp -d)\u002Fproof\ngit worktree add --detach \"$SCRATCH\" HEAD\nexport CARGO_TARGET_DIR=\"$PWD\u002Ftarget\"   # reuse the warm build\n# TS, no workspace packages: ln -s \"$PWD\u002Fnode_modules\" \"$SCRATCH\u002Fnode_modules\"\n# TS, in a workspace: (cd \"$SCRATCH\" && npm ci --offline) or (cd \"$SCRATCH\" && pnpm install --offline --frozen-lockfile)\n# apply ONE breaking edit from the worklist by hand inside $SCRATCH, then:\n(cd \"$SCRATCH\" && timeout 1800 cargo test -p example_crate)\n(cd \"$SCRATCH\" && timeout 1800 cargo test -p example_crate a_file_ttl_cannot_outlive_the_ceiling)\ngit worktree remove --force \"$SCRATCH\"\n```\n\nSwap the commands for the repo's runner, with a name filter for the second, such\nas `uv run pytest -k NAME`, `npx vitest run FILE -t NAME` or `go test -run NAME .\u002Fpkg\u002F`,\nor the lint or type check itself (`cargo clippy`, `tsc --noEmit`, `npx pyright`).\nA shared environment that resolves the package back to the main tree, such as\nan editable install or a symlinked `node_modules` in a workspace, never sees\nthe edit; install offline from the lockfile there instead.\n\n| Outcome | Counts as |\n|---|---|\n| The test prints a failure, or the lint or type check errors on the edited line | Owner proven for this edit |\n| A build error from a leftover the edit orphaned, such as an unused import or binding under deny-warnings | No result. Remove the leftover and run again |\n| Exit 124 with no test result line | Proven only when the guard's stated consequence is the hang itself |\n| The candidate already fails on the unmodified scratch copy | Not an owner. It proves nothing about this edit |\n| The owner stays green | Not an owner. The prose stays |\n| Two tests, one fails | Only the failing test is an owner |\n| The owner is compiled out on this host, such as a platform-gated assert | Unproven here. Run it on its target platform, or the prose stays |\n\n- The pointer names every test that failed on the edit and none that stayed\n  green. Name the symbol, never a plan ID or a `file:line` (RTE-05).\n- Keep that one local line naming the owner, even when the owning construct\n  states itself, such as `assert_never(x)` or a scoped `#[deny(...)]`. This\n  skill never cuts a guard to nothing (RTE-03).\n- Any breaking edit without a proven owner keeps its mechanism, the edit and\n  the consequence.\n- A mutation tool is optional support, never the proof. Budget one warm build\n  per repo, then seconds per test.\n\n### 6. Split an essay\n\n- Guard, contract and why clauses stay, rewritten per step 4.\n- An argument clause (alternatives weighed, the design story) goes one of three\n  ways:\n  - A tracked record already holds it in its own words: delete it, keep one\n    pointer to that record, and pass the record to the check with `--cites`\n    (RTE-09). The check lists `--cites` records for a human to confirm.\n  - It argues a decision someone could reopen, and it is not limited in scope,\n    time, risk and cost: append it to a decision record, and the code keeps one\n    pointer (RTE-10).\n  - Otherwise the choice is small: keep its conclusion as one why sentence when\n    the code does not show it, and delete the rest.\n- A pointer is `path\u002Fto\u002Frecord.md#section`. The file is tracked (LNK-02). The\n  anchor is the shortest unique heading prefix, never a line number (LNK-03).\n  Never point at a commit, a branch, a backup ref or a gitignored path (RTE-02).\n- A record is new, or receives additions only. Declare each one to the check with\n  `--relocation` (CLN-05). The moved text must land there, and the paraphrase\n  never stays beside the pointer (CLN-04).\n- An added record pointer is legal only when the block named that file before\n  the edit, or the file is a `--relocation` or `--cites` record. The check fails\n  any other (CLN-04, LNK-05).\n- Some clauses belong somewhere this diff may not touch. A universal negative\n  belongs on the doc comment of the test that asserts it (RTE-04). An invariant\n  true at every file a path-scoped rule matches belongs in that rule (RTE-07).\n  Leave these where they are and list them in the report.\n\n### 7. Remove bare IDs, carry every pointer\n\n- Delete a bare process ID and keep the constraint it labelled, in words\n  (LNK-01). This covers the rule's families, the repo's own families (LNK-14),\n  and a short label cited outside the block that defines it (LNK-13).\n- Add a record pointer in its place only when the same block already names that\n  file, or when you have read the record and it holds the removed argument in\n  its own words, passed to the check with `--cites` (LNK-05). Never guess which\n  document a colliding ID meant. A pointer that replaces prose the ID labelled\n  follows step 6.\n- Keep every file-qualified pointer (GRD-11):\n  - A pointer to a record that moved: find the move and repoint it (LNK-10).\n  - A dead pointer you cannot trace: leave it and report it.\n  - A pointer to a commit, a branch or an untracked path is no pointer\n    (RTE-02). Replace it with the constraint it stood for, stated in words.\n\n### 8. Run the structural gate\n\n```\npython3 \"$CHECKS\u002Fcleanup_check.py\" --base \"$BASE\" --relocation docs\u002Fadr\u002F0042-example-record.md --cites docs\u002Fdesign\u002Fdecisions.md\n```\n\nPass `--relocation` once per record that received text, and `--cites` once per\nrecord a new pointer names because it already held the removed argument (step\n6). Drop a flag that has no record. Exit 1 lists blocking findings, including\nany added pointer step 6 does not allow: fix each one and run it again. Exit 0\nmay still print `CLN-02 review` items and the `--cites` records. Read each\nreview item against the worklist: every breaking edit still has its own\nsentence.\n\nThen check that no pointer was dropped (GRD-11). This prints the pointers the\ndiff removed and did not add back:\n\n```\nMB=$(git merge-base \"$BASE\" HEAD)\ncomm -23 \u003C(git diff -U0 \"$MB\" -- . ':(exclude)*.md' | grep -e '^-' | grep -v -e '^---' | grep -oE -e '[A-Za-z0-9_.\u002F-]+\\.md' | sort -u) \u003C(git diff -U0 \"$MB\" -- . ':(exclude)*.md' | grep -e '^+' | grep -v -e '^+++' | grep -oE -e '[A-Za-z0-9_.\u002F-]+\\.md' | sort -u)\n```\n\nThen run the repo's full local check chain: every CI job for these files and\nevery task-runner target (`task check`, `make check`, `npm run` scripts), not\nonly what CI runs. Run it at `BASE` first, in a scratch worktree or before the\nfirst edit. Only a failure new since `BASE` counts; report the pre-existing\nreds. The chain must include:\n\n- the doctests: Rust `cargo test --doc` on each crate with a lib target, and\n  Python `pytest --doctest-modules` where the repo uses doctests;\n- the doc build with warnings denied, which catches a broken intra-doc link:\n  `RUSTDOCFLAGS='-D warnings' cargo doc --no-deps`;\n- the type checker, where a deleted `@ts-expect-error` or `# type: ignore`\n  surfaces;\n- the linter.\n\n### 9. Re-check the reason for every shortened guard\n\nFor each guard you shortened, run a fresh read-only session against an\nexported copy of the edited tree with no git history, so the probe can read\nneither the commit message that carries the guard's reason (step 10) nor the\nold comment through git. Ask the unled question first (\"Why is it written this\nway? Could it be written differently without changing anything that\nmatters?\"), score it, and only then ask the led question naming the recorded\nbreaking edit (CLN-06). Prompts, command and scoring are in\n[references\u002Freason-recheck.md](references\u002Freason-recheck.md).\n\n- It is SHOULD for touched files and required for every shortened guard in a\n  sweep file.\n- Touched files run it before the commit. A sweep commits one file at a time\n  and runs it once, over every guard the sweep shortened, before the final\n  report.\n- A guard passes at mechanism plus consequence with a `keep` verdict. Anything\n  lower goes back to step 4, rewritten or restored from the base. In a sweep,\n  that fix is a new commit that passes step 8 again.\n\n### 10. Commit\n\n- Commit the cleanup on its own, with only prose in it. Never fold it into a code\n  commit, and never squash it into one later.\n- In a sweep, one file per commit, together with any record that file's prose\n  moved to.\n- If the repo keeps the rule's baselines, record the drop in the same commit,\n  never with `--allow-regression`, and let `--check` confirm it (LEN-03,\n  LNK-01). Do it after step 8: `cleanup_check.py` fails any changed non-source\n  path, baselines included.\n\n```\npython3 \"$CHECKS\u002Fcomment_census.py\" --root . --update .code-docs-length.json\npython3 \"$CHECKS\u002Flinkage_check.py\" ids --root . --update .code-docs-linkage.json\npython3 \"$CHECKS\u002Flinkage_check.py\" pointers --root . --update .code-docs-linkage.json\npython3 \"$CHECKS\u002Fcomment_census.py\" --root . --check .code-docs-length.json\n```\n\n- In the body, list each shortened guard with its proof: the owner that failed,\n  or the re-check level (in a sweep, the final report carries the levels). Also\n  list the records that received text and what was left for another change.\n\n## Never touch\n\n`cleanup_check.py` fails the diff on each of these. Knowing them up front\nsaves the rerun.\n\n| Line or path | What goes wrong | Rule |\n|---|---|---|\n| Code, including a comment that shares its line with code | A \"comment-only\" diff changes behaviour | CLN-03 |\n| Doc text that renders to users (clap, schemars, click, typer, pydantic, MCP tools, files under `interface_files`) | The user contract changes, and goldens drift | CLN-03 |\n| Tool directives: `@ts-expect-error`, `# noqa`, `# type: ignore`, `eslint-disable`, `nolint`, `\u002F\u002Fgo:build` | The build or the lint result changes | CLN-03 |\n| Licence headers | Legal text changes | CLN-03 |\n| Fenced code, a Python `Example:`\u002F`Examples:` section, a reST `::` literal block, and a `>>>` doctest line, inside doc comments | A test is deleted | CLN-03 |\n| A Python docstring that is the function's only statement | The body empties and the file stops parsing | CLN-03 |\n| Adding or deleting a source file | Code moves under cover of prose | CLN-03 |\n| Test files and in-file test regions such as `#[cfg(test)]` | A test is \"tidied\" | CLN-05 |\n| Lock, manifest, generated, golden or snapshot files | Dependencies or recorded output change | CLN-05 |\n| Any other non-source path, except a declared record that only grows | Unreviewed edits ride along | CLN-05 |\n\n## Cleanup rules\n\nMUST = Block. SHOULD = Warn: fix, or state why not in the commit body.\n\n| ID | Rule | Verification | Severity |\n|---|---|---|---|\n| CLN-01 | Classify every block clause by clause, guard first. Delete only a clause positively identified as narration, tautology, a banner, a bare ID or unquantified pure provenance. A block that matches nothing, or that the recogniser flags, stays. | Each deletion passes its decision-list test read against the code. `cleanup_check.py` fails a flagged or labelled block removed whole with no replacement | MUST |\n| CLN-02 | Before shortening a guard block over 5 lines, split it into clauses. Every clause naming a breaking edit and its consequence keeps its own sentence at the line it guards. Never paraphrase several guards into one line. | List every edit the block forbade and find each surviving sentence. `cleanup_check.py` prints `CLN-02 review` items and never fails on them | MUST |\n| CLN-03 | Leave every non-prose line byte-identical: code, interface doc text, tool directives, licence headers, fenced code and doctests. A Python `Example:`\u002F`Examples:` section and a reST `::` literal block are frozen the same way as fenced code. A Python file that parsed at the base still parses. | `cleanup_check.py`, then the repo's own build, doc, doctest and lint gate | MUST |\n| CLN-04 | Removed prose is gone: it never reappears at 80% token overlap or more in the file's other comments, a declared relocation lands in its record, and a pointer never sits beside the paraphrase it replaced. An added record pointer names a file the block named before the edit, a `--relocation` record, or a `--cites` record that already holds the removed argument. Every input comes from the diff, never from a list the editing agent wrote. | `cleanup_check.py`, with `--relocation` and `--cites` once per record; a human confirms each `--cites` record | MUST |\n| CLN-05 | Touch no test file or in-file test region, lock or manifest, generated or golden file, or non-source path other than a declared record that is new or only grows. | `cleanup_check.py`. `RECORD=docs\u002Fadr\u002F0042-example-record.md; git diff --numstat \"$BASE\" -- \"$RECORD\"` shows 0 deleted lines | MUST |\n| CLN-06 | Re-check every shortened guard in a fresh read-only session: the unled question first, scored for mechanism plus consequence, then the led question naming the recorded breaking edit. A `may-change` after a strong unled answer fails. | Step 9, with [references\u002Freason-recheck.md](references\u002Freason-recheck.md) | SHOULD; required for every shortened guard in a sweep |\n| CLN-07 | Shrink a guard to a one-line pointer only when every breaking edit it names has an owner that failed on that edit in a scratch copy: an enabled lint, a scoped `deny`, a type check or any test, named in the block or not. The pointer names every test that failed and none that stayed green. An edit with no proven owner keeps its mechanism, edit and consequence. | Step 5's planted-edit run, once per owner and edit | MUST |\n| CLN-08 | Clean only the files the change already touches. A sweep runs one file per commit and skips any file another branch or an open pull request has in flight, checked before starting it and again before merge. | The two commands under [Scope](#scope) print nothing | SHOULD |\n\n## Report\n\nReturn, per file:\n\n- over-cap lines before and after, from `--over-cap`;\n- blocks deleted, guards shortened (each with its owner proof or re-check level),\n  and records that received text;\n- every `CLN-02 review` item, and how you resolved it;\n- every `--cites` record, for a human to confirm it holds the removed argument;\n- gate failures already red at `BASE`, and files whose in-flight check was\n  unavailable;\n- what you left for another change: interface leaks, test-doc and rule\n  candidates, dead pointers, local-rule conflicts, commented-out code, a clause\n  the code contradicts, bare IDs in tests with the file's `bare-id-test` count,\n  and any guard whose consequence you could not state.\n\n## MUST rows this procedure surfaces\n\nRestated so a cleanup run without the rule loaded still reports them with the\nright ID. [Cleanup rules](#cleanup-rules) and the installed rule hold the text\nand full verification.\n\n| # | Finding | Rule |\n|---|---|---|\n| 1 | A block deleted without being positively identified as narration, tautology, a banner, a bare ID or unquantified pure provenance | CLN-01 |\n| 2 | A recogniser-flagged block, a `SAFETY:` label, a deferred-shortcut marker, or a comment another rule mandates, removed whole with no replacement | CLN-01, GRD-06 |\n| 3 | A block over 3 lines routed whole instead of clause by clause | RTE-01 |\n| 4 | A guard block over 5 lines shortened without a clause split, or several guards paraphrased into one line | CLN-02 |\n| 5 | A guard cut below constraint plus consequence | GRD-01 |\n| 6 | A non-prose line changed: code, interface text, a directive, a licence header, fenced code or a doctest | CLN-03 |\n| 7 | Removed prose survives elsewhere in the file, a declared relocation did not land, or a pointer sits beside the paraphrase it replaced | CLN-04 |\n| 8 | The diff touches a test or test region, a lock or manifest, a generated or golden file, or a non-source path other than a declared record that only grows | CLN-05 |\n| 9 | A guard shrunk to a pointer without a failing planted-edit run for every breaking edit, or a pointer naming a test that stayed green | CLN-07, GRD-07, RTE-03 |\n| 10 | A file-qualified pointer dropped without the same target reappearing | GRD-11 |\n| 11 | A record pointer added to a file the block did not name before the edit, that is neither a `--relocation` nor a `--cites` record | CLN-04, LNK-05 |\n| 12 | A pointer to a commit, a branch, a backup ref or a gitignored path | RTE-02 |\n| 13 | A record pointer that does not resolve to a tracked file | LNK-02 |\n\n## What agents get wrong\n\nRanked, most frequent first. Each mode, its tell and its catch are in\n[references\u002Ffailure-modes.md](references\u002Ffailure-modes.md).\n\n1. **Collapsing a guard bundle into one paraphrase**, dropping the consequence\n   clause first.\n2. **Deleting by category or length:** \"long means essay\", \"past tense means\n   history\", \"`Step N:` means narration\".\n3. **Crediting an owner by its name.** A test named after the constraint often\n   stays green on the breaking edit.\n4. **Adding the pointer and keeping the essay** beside it.\n5. **Reporting success from its own reading** instead of the check and the\n   re-check.\n6. **Incidental edits outside prose:** a help string, a directive, a doctest.\n\n## References\n\n| Read | When |\n|---|---|\n| [references\u002Fdecision-list.md](references\u002Fdecision-list.md) | Step 3 and 4: tagging a clause, writing a guard, choosing the register, meeting a cap |\n| [references\u002Freason-recheck.md](references\u002Freason-recheck.md) | Step 9: the unled and led prompts, the session command, the scoring levels |\n| [references\u002Ffailure-modes.md](references\u002Ffailure-modes.md) | Before a sweep, or when a check fails and the cause is unclear |\n","# code-docs-cleanup\n\nShorten the comments in a source file without losing a guard. A guard is any\nclause that names a constraint a plausible edit would break, with or without the\nconsequence. It is how the next agent learns why a non-obvious line looks the way\nit does and whether it may change it.\n\nThe comment standards live in the installed `code-docs` rule, cited here by\nID: GRD (guards), RTE (routing), LNK (pointers and IDs), SRF (rendered\nsurfaces) and LEN (length and ratchet). The cleanup-safety rules, CLN, are this\nskill's own: [Cleanup rules](#cleanup-rules). Three facts shape every step (as\nof 2026-09):\n\n- In agent-written code most comment lines are guards and contracts, not essays.\n  Deleting by category or by length deletes guards.\n- The shipped guard recogniser finds fewer than half of real guards (recall\n  about 0.43). A block it does not flag is unclassified, never safe to cut.\n- The editing agent's belief that the meaning survived is not evidence. The\n  structural check and a cold re-check are.\n\nContents: [When to run](#when-to-run) · [Setup](#setup) · [Scope](#scope) ·\n[Procedure](#procedure) · [Never touch](#never-touch) · [Cleanup rules](#cleanup-rules) · [Report](#report) ·\n[MUST rows](#must-rows-this-procedure-surfaces) ·\n[What agents get wrong](#what-agents-get-wrong) · [References](#references)\n\n## When to run\n\nRun it when:\n\n- A change already edits a file whose comments are over the length caps\n  (LEN-01, LEN-02), carry bare process IDs (LNK-01), or hold an essay.\n- The owner names files for a sweep, or asks to bring a package down before its\n  ratchet baseline is recorded (LEN-03).\n- A review flags an over-cap block, or a pointer left beside the essay it was\n  meant to replace (RTE-09).\n\nDo not run it when:\n\n- The text renders to users: `--help`, JSON Schema, MCP tool descriptions,\n  argparse or commander help, or a published package's API docs. That is an\n  interface change (SRF-01, SRF-02). It moves rationale into plain comments and\n  may regenerate goldens, which this skill never does.\n- The file is a test, generated, vendored, a lock or manifest file, or a golden.\n  Bare IDs in test files and test regions (LNK-01's `bare-id-test` key) go in a\n  separate test-only change: list them in the report.\n- Another branch has the file in flight (see [Scope](#scope)).\n- The fix is code: a type that owns a guard (GRD-12), a lint to enable (GRD-09,\n  GRD-10), a test to rename. Each is its own reviewable diff.\n- The repo's own rules protect the comment kind, for example a local rule that\n  keeps section dividers or phase markers. The local rule wins until it is\n  amended. Leave those comments and report the conflict.\n\n## Setup\n\n1. Find the rule's checks, in the project first, then in the global client\n   directories:\n   `find . \"$HOME\u002F.claude\" \"$HOME\u002F.config\" -path '*\u002Fcode-docs\u002Fchecks\u002Fcleanup_check.py' -not -path '*\u002Fnode_modules\u002F*' 2>\u002Fdev\u002Fnull | head -n 1`.\n   `CHECKS` below is the directory of that hit; any installed copy works. Read\n   the `code-docs.md` index installed beside the `code-docs\u002F` folder. No hit\n   means the rule is installed neither in the project nor globally: install it\n   with `grim add ghcr.io\u002Focx-sh\u002Flore\u002Fcode-docs`. Where the client tool cannot\n   install it, copy `code-docs.md` and the `code-docs\u002F` folder from the rule's\n   source into the client's rules directory (such as `.claude\u002Frules\u002F`) with\n   `rsync -a --exclude __pycache__` or `git archive`, so no stale `.pyc` file\n   rides along, commit that on its own before the cleanup, and run the find\n   again.\n2. `python3 \"$CHECKS\u002Fcleanup_check.py\" --self-test` and\n   `python3 \"$CHECKS\u002Fguard_recogniser.py\" --self-test` both exit 0.\n3. `git status --porcelain` lists nothing untracked that the cleanup did not\n   create. `cleanup_check.py` reads every untracked file as an added path and\n   fails it (CLN-05). An untracked file you did not create is the owner's: never\n   delete or revert it. Run the cleanup from a clean worktree, or ask the owner\n   to move the file.\n4. Pick the mode and set `BASE=HEAD`. The check fails any non-prose line that\n   differs from the base, so the working tree holds only uncommitted cleanup:\n   the touched files', or in a sweep one file's.\n\n| Mode | When | Before each file |\n|---|---|---|\n| Touched files (default) | Cleaning files the current change already edits | Commit the change's code first |\n| Sweep | The owner named files, or asked for a package sweep | Commit the previous file's cleanup, on a branch made for the sweep from the default branch |\n\n5. Declare every library-kind package in `.code-docs.json` before ranking or\n   cleaning anything: `python3 \"$CHECKS\u002Fcomment_census.py\" --root . --report`\n   lists undeclared packages that look published. The caps, and so the scope\n   of the sweep, depend on the declaration.\n\nCaps are the rule's defaults: plain blocks 5 lines, doc blocks 10, or 15 for a\npublic item in a library-kind package. The census reads them, and the list of\nlibrary packages, from `.code-docs.json` at the repo root. An adopter may\noverride both there, and list under `interface_files` the sources a generator\nthe checks do not know renders, such as a TS-to-JSON-Schema script. Their doc\ncomments are then frozen like clap's.\n\n## Scope\n\n- **Touched files:** only the files the change already edits (CLN-08). Never\n  widen to a neighbour because it looks worse.\n- **Sweep:** one file per commit (CLN-08). Rank packages with\n  `python3 \"$CHECKS\u002Fcomment_census.py\" --root . --report` and files with\n  `--over-cap`. Before starting a file, and again before merge, skip it if either\n  command prints anything:\n\n```\nFILE=src\u002Fexample.rs; MAIN=origin\u002Fmain; SELF=$(git branch --show-current)\ngit worktree list --porcelain | grep -e '^branch' | cut -d\u002F -f3- | grep -v -x -F -e \"$SELF\" | xargs -r -I{} git log -1 --format='{} %h %cs' \"$MAIN..{}\" -- \"$FILE\" || echo \"in-flight check unavailable\"\nFILE=src\u002Fexample.rs gh pr list --state open --limit 100 --json headRefName,files --jq '.[] | select(any(.files[]; .path == env.FILE)) | .headRefName' || echo \"in-flight check unavailable\"\n```\n\nThe first names a worktree branch with commits on the file, the second an open\npull request that edits it. Commit age settles nothing: a branch idle for a\nweek still merges. `in-flight check unavailable` means unknown, never clear:\nlist the file as unchecked in the report and have the owner confirm it before\nmerge.\n\n## Procedure\n\nWork one file at a time, one block at a time, top to bottom. Steps 1 to 3 read\nand classify every block. Steps 3 to 7 edit prose only, and only in over-cap\nblocks, blocks with a bare ID, and guards that fail GRD-01 or GRD-05. Every\nother block stays byte-identical. Steps 8 to 10 prove the edit.\n\n### 1. List the blocks\n\n```\nFILE=src\u002Fexample.rs\npython3 \"$CHECKS\u002Fcomment_census.py\" --root . --over-cap | grep -F -e \"$FILE:\"\npython3 \"$CHECKS\u002Fguard_recogniser.py\" --root . | grep -F -e \"$FILE:\"\npython3 \"$CHECKS\u002Flinkage_check.py\" ids --root . | grep -F -e \"$FILE:\"\npython3 \"$CHECKS\u002Flinkage_check.py\" pointers --root . | grep -F -e \"$FILE:\"\ngit grep -n -F -e \"${FILE##*\u002F}\" -- . \":(exclude)$FILE\" ':(exclude)*.md'\nMODULE=example; DOTTED=package.example   # the module without its extension, and its Python dotted path\ngit grep -n -F -e \"$MODULE.js\" -e \"$MODULE'\" -e \"$DOTTED\" -- . \":(exclude)$FILE\" ':(exclude)*.md'\ngit grep -n -F -e \"::: $DOTTED\" -e \"automodule:: $DOTTED\" -- .\n```\n\nThe first four rank the work. They do not bound it: every comment block in the\nfile goes through step 3, flagged or not. The rest find every reader, under\nevery name it can use: the path (a script, task file, CI config or test), the\nmodule name without its extension (a TS\u002FJS import ending in `.js`), the Python\ndotted module path, and a doc-generator directive (mkdocstrings `::: pkg.module`,\nSphinx `automodule::`). Never exclude `*.md` from the directive search: a hit\nthere means the module's docstrings render into published docs, so treat them\nas interface text (CLN-03). Read every hit; a name can match an unrelated file\n(`_rest.py` also matches `01_shellcheck_rest.py`). One that reads the file owns\nits comment text: text a check asserts stays verbatim. Record each in the\nworklist.\n\n### 2. Record every guard before you edit\n\nWrite a worklist in a scratch directory outside the repo. One row per guard\nclause: the line it guards, the constraint, the breaking edit, the consequence,\nand any owner the text claims (a test, a lint, a type). When unsure whether a\nclause is a guard, it is one.\n\nThe worklist feeds steps 5, 8 and 9. It is never an input to the check, which\nderives everything from the diff so that the editing agent never writes its own\ngrading input (CLN-04).\n\n### 3. Classify clause by clause, guard first\n\nSplit every block into clauses and tag each with\n[references\u002Fdecision-list.md](references\u002Fdecision-list.md) (RTE-01). Check for a\nguard before anything else.\n\n- Delete a clause outright only when the list positively identifies it as\n  narration, tautology, a banner, a bare ID or unquantified pure provenance\n  (CLN-01). Argument and record paraphrase leave only through step 6.\n- Length, a history phrase or a `Step N:` opener identifies nothing.\n- A block the recogniser flags, a `SAFETY:` label, the repo's deferred-shortcut\n  marker (for example `ponytail:`) and a comment another rule mandates (a\n  discard rationale, a lint-suppression reason) are never deleted whole (GRD-06).\n- Text a repo check asserts (step 1) stays verbatim.\n- A clause that fits no row stays.\n\n### 4. Rewrite each guard as fact plus consequence, at its line\n\n- Keep the constraint and the concrete consequence of breaking it. No edit goes\n  below that floor (GRD-01). \"Important\", \"careful\" or \"load-bearing\" alone is\n  not a consequence.\n- Keep nothing else in the guard: no history, no weighed alternatives, no bare\n  ID. Name the tempting edit only when the constraint does not imply it, and\n  name the sibling the code must not be unified with when that is the risk\n  (GRD-02).\n- Split a guard block over 5 lines clause by clause. Every breaking edit the\n  original forbade keeps its own sentence, at the line it guards. Never\n  paraphrase several guards into one line (CLN-02, LEN-05). State each guard\n  once (GRD-03).\n- Phrase it as a present-tense fact, never a command to the reader (GRD-05).\n  History that still constrains an edit becomes a present-tense guard (RTE-11).\n- Put a caller-visible precondition in the doc comment and an implementation\n  hazard in a plain comment at its line (GRD-04). Add no marker prefix.\n  `SAFETY:` stays where the language uses it.\n- When the guard clauses alone exceed the cap, keep them all and tighten the\n  wording. The cap never drops a guard.\n- Rewrite a clause as you move it. The check fails prose the recogniser does\n  not flag that reappears, 80% or more intact, elsewhere in the same file\n  (CLN-04).\n- Never invent a consequence the original does not state and the code does not\n  show. Keep the original wording and list the block in the report.\n\n### 5. Shrink a guard to its owner only after a planted edit fails it\n\nA guard shrinks to a one-line pointer only when every breaking edit it names\nhas a proven owner (CLN-07, GRD-07, RTE-03). An owner is an enabled lint, a\nscoped `deny`, a type check, or any test, named in the block or not. It is\nproven only when it passes on the unmodified scratch copy and fails on that\nexact edit applied to the same copy: a test already red before the edit proves\nnothing. Run the suite on the planted edit to find the candidates, then each\nred test alone:\n\n```\nSCRATCH=$(mktemp -d)\u002Fproof\ngit worktree add --detach \"$SCRATCH\" HEAD\nexport CARGO_TARGET_DIR=\"$PWD\u002Ftarget\"   # reuse the warm build\n# TS, no workspace packages: ln -s \"$PWD\u002Fnode_modules\" \"$SCRATCH\u002Fnode_modules\"\n# TS, in a workspace: (cd \"$SCRATCH\" && npm ci --offline) or (cd \"$SCRATCH\" && pnpm install --offline --frozen-lockfile)\n# apply ONE breaking edit from the worklist by hand inside $SCRATCH, then:\n(cd \"$SCRATCH\" && timeout 1800 cargo test -p example_crate)\n(cd \"$SCRATCH\" && timeout 1800 cargo test -p example_crate a_file_ttl_cannot_outlive_the_ceiling)\ngit worktree remove --force \"$SCRATCH\"\n```\n\nSwap the commands for the repo's runner, with a name filter for the second, such\nas `uv run pytest -k NAME`, `npx vitest run FILE -t NAME` or `go test -run NAME .\u002Fpkg\u002F`,\nor the lint or type check itself (`cargo clippy`, `tsc --noEmit`, `npx pyright`).\nA shared environment that resolves the package back to the main tree, such as\nan editable install or a symlinked `node_modules` in a workspace, never sees\nthe edit; install offline from the lockfile there instead.\n\n| Outcome | Counts as |\n|---|---|\n| The test prints a failure, or the lint or type check errors on the edited line | Owner proven for this edit |\n| A build error from a leftover the edit orphaned, such as an unused import or binding under deny-warnings | No result. Remove the leftover and run again |\n| Exit 124 with no test result line | Proven only when the guard's stated consequence is the hang itself |\n| The candidate already fails on the unmodified scratch copy | Not an owner. It proves nothing about this edit |\n| The owner stays green | Not an owner. The prose stays |\n| Two tests, one fails | Only the failing test is an owner |\n| The owner is compiled out on this host, such as a platform-gated assert | Unproven here. Run it on its target platform, or the prose stays |\n\n- The pointer names every test that failed on the edit and none that stayed\n  green. Name the symbol, never a plan ID or a `file:line` (RTE-05).\n- Keep that one local line naming the owner, even when the owning construct\n  states itself, such as `assert_never(x)` or a scoped `#[deny(...)]`. This\n  skill never cuts a guard to nothing (RTE-03).\n- Any breaking edit without a proven owner keeps its mechanism, the edit and\n  the consequence.\n- A mutation tool is optional support, never the proof. Budget one warm build\n  per repo, then seconds per test.\n\n### 6. Split an essay\n\n- Guard, contract and why clauses stay, rewritten per step 4.\n- An argument clause (alternatives weighed, the design story) goes one of three\n  ways:\n  - A tracked record already holds it in its own words: delete it, keep one\n    pointer to that record, and pass the record to the check with `--cites`\n    (RTE-09). The check lists `--cites` records for a human to confirm.\n  - It argues a decision someone could reopen, and it is not limited in scope,\n    time, risk and cost: append it to a decision record, and the code keeps one\n    pointer (RTE-10).\n  - Otherwise the choice is small: keep its conclusion as one why sentence when\n    the code does not show it, and delete the rest.\n- A pointer is `path\u002Fto\u002Frecord.md#section`. The file is tracked (LNK-02). The\n  anchor is the shortest unique heading prefix, never a line number (LNK-03).\n  Never point at a commit, a branch, a backup ref or a gitignored path (RTE-02).\n- A record is new, or receives additions only. Declare each one to the check with\n  `--relocation` (CLN-05). The moved text must land there, and the paraphrase\n  never stays beside the pointer (CLN-04).\n- An added record pointer is legal only when the block named that file before\n  the edit, or the file is a `--relocation` or `--cites` record. The check fails\n  any other (CLN-04, LNK-05).\n- Some clauses belong somewhere this diff may not touch. A universal negative\n  belongs on the doc comment of the test that asserts it (RTE-04). An invariant\n  true at every file a path-scoped rule matches belongs in that rule (RTE-07).\n  Leave these where they are and list them in the report.\n\n### 7. Remove bare IDs, carry every pointer\n\n- Delete a bare process ID and keep the constraint it labelled, in words\n  (LNK-01). This covers the rule's families, the repo's own families (LNK-14),\n  and a short label cited outside the block that defines it (LNK-13).\n- Add a record pointer in its place only when the same block already names that\n  file, or when you have read the record and it holds the removed argument in\n  its own words, passed to the check with `--cites` (LNK-05). Never guess which\n  document a colliding ID meant. A pointer that replaces prose the ID labelled\n  follows step 6.\n- Keep every file-qualified pointer (GRD-11):\n  - A pointer to a record that moved: find the move and repoint it (LNK-10).\n  - A dead pointer you cannot trace: leave it and report it.\n  - A pointer to a commit, a branch or an untracked path is no pointer\n    (RTE-02). Replace it with the constraint it stood for, stated in words.\n\n### 8. Run the structural gate\n\n```\npython3 \"$CHECKS\u002Fcleanup_check.py\" --base \"$BASE\" --relocation docs\u002Fadr\u002F0042-example-record.md --cites docs\u002Fdesign\u002Fdecisions.md\n```\n\nPass `--relocation` once per record that received text, and `--cites` once per\nrecord a new pointer names because it already held the removed argument (step\n6). Drop a flag that has no record. Exit 1 lists blocking findings, including\nany added pointer step 6 does not allow: fix each one and run it again. Exit 0\nmay still print `CLN-02 review` items and the `--cites` records. Read each\nreview item against the worklist: every breaking edit still has its own\nsentence.\n\nThen check that no pointer was dropped (GRD-11). This prints the pointers the\ndiff removed and did not add back:\n\n```\nMB=$(git merge-base \"$BASE\" HEAD)\ncomm -23 \u003C(git diff -U0 \"$MB\" -- . ':(exclude)*.md' | grep -e '^-' | grep -v -e '^---' | grep -oE -e '[A-Za-z0-9_.\u002F-]+\\.md' | sort -u) \u003C(git diff -U0 \"$MB\" -- . ':(exclude)*.md' | grep -e '^+' | grep -v -e '^+++' | grep -oE -e '[A-Za-z0-9_.\u002F-]+\\.md' | sort -u)\n```\n\nThen run the repo's full local check chain: every CI job for these files and\nevery task-runner target (`task check`, `make check`, `npm run` scripts), not\nonly what CI runs. Run it at `BASE` first, in a scratch worktree or before the\nfirst edit. Only a failure new since `BASE` counts; report the pre-existing\nreds. The chain must include:\n\n- the doctests: Rust `cargo test --doc` on each crate with a lib target, and\n  Python `pytest --doctest-modules` where the repo uses doctests;\n- the doc build with warnings denied, which catches a broken intra-doc link:\n  `RUSTDOCFLAGS='-D warnings' cargo doc --no-deps`;\n- the type checker, where a deleted `@ts-expect-error` or `# type: ignore`\n  surfaces;\n- the linter.\n\n### 9. Re-check the reason for every shortened guard\n\nFor each guard you shortened, run a fresh read-only session against an\nexported copy of the edited tree with no git history, so the probe can read\nneither the commit message that carries the guard's reason (step 10) nor the\nold comment through git. Ask the unled question first (\"Why is it written this\nway? Could it be written differently without changing anything that\nmatters?\"), score it, and only then ask the led question naming the recorded\nbreaking edit (CLN-06). Prompts, command and scoring are in\n[references\u002Freason-recheck.md](references\u002Freason-recheck.md).\n\n- It is SHOULD for touched files and required for every shortened guard in a\n  sweep file.\n- Touched files run it before the commit. A sweep commits one file at a time\n  and runs it once, over every guard the sweep shortened, before the final\n  report.\n- A guard passes at mechanism plus consequence with a `keep` verdict. Anything\n  lower goes back to step 4, rewritten or restored from the base. In a sweep,\n  that fix is a new commit that passes step 8 again.\n\n### 10. Commit\n\n- Commit the cleanup on its own, with only prose in it. Never fold it into a code\n  commit, and never squash it into one later.\n- In a sweep, one file per commit, together with any record that file's prose\n  moved to.\n- If the repo keeps the rule's baselines, record the drop in the same commit,\n  never with `--allow-regression`, and let `--check` confirm it (LEN-03,\n  LNK-01). Do it after step 8: `cleanup_check.py` fails any changed non-source\n  path, baselines included.\n\n```\npython3 \"$CHECKS\u002Fcomment_census.py\" --root . --update .code-docs-length.json\npython3 \"$CHECKS\u002Flinkage_check.py\" ids --root . --update .code-docs-linkage.json\npython3 \"$CHECKS\u002Flinkage_check.py\" pointers --root . --update .code-docs-linkage.json\npython3 \"$CHECKS\u002Fcomment_census.py\" --root . --check .code-docs-length.json\n```\n\n- In the body, list each shortened guard with its proof: the owner that failed,\n  or the re-check level (in a sweep, the final report carries the levels). Also\n  list the records that received text and what was left for another change.\n\n## Never touch\n\n`cleanup_check.py` fails the diff on each of these. Knowing them up front\nsaves the rerun.\n\n| Line or path | What goes wrong | Rule |\n|---|---|---|\n| Code, including a comment that shares its line with code | A \"comment-only\" diff changes behaviour | CLN-03 |\n| Doc text that renders to users (clap, schemars, click, typer, pydantic, MCP tools, files under `interface_files`) | The user contract changes, and goldens drift | CLN-03 |\n| Tool directives: `@ts-expect-error`, `# noqa`, `# type: ignore`, `eslint-disable`, `nolint`, `\u002F\u002Fgo:build` | The build or the lint result changes | CLN-03 |\n| Licence headers | Legal text changes | CLN-03 |\n| Fenced code, a Python `Example:`\u002F`Examples:` section, a reST `::` literal block, and a `>>>` doctest line, inside doc comments | A test is deleted | CLN-03 |\n| A Python docstring that is the function's only statement | The body empties and the file stops parsing | CLN-03 |\n| Adding or deleting a source file | Code moves under cover of prose | CLN-03 |\n| Test files and in-file test regions such as `#[cfg(test)]` | A test is \"tidied\" | CLN-05 |\n| Lock, manifest, generated, golden or snapshot files | Dependencies or recorded output change | CLN-05 |\n| Any other non-source path, except a declared record that only grows | Unreviewed edits ride along | CLN-05 |\n\n## Cleanup rules\n\nMUST = Block. SHOULD = Warn: fix, or state why not in the commit body.\n\n| ID | Rule | Verification | Severity |\n|---|---|---|---|\n| CLN-01 | Classify every block clause by clause, guard first. Delete only a clause positively identified as narration, tautology, a banner, a bare ID or unquantified pure provenance. A block that matches nothing, or that the recogniser flags, stays. | Each deletion passes its decision-list test read against the code. `cleanup_check.py` fails a flagged or labelled block removed whole with no replacement | MUST |\n| CLN-02 | Before shortening a guard block over 5 lines, split it into clauses. Every clause naming a breaking edit and its consequence keeps its own sentence at the line it guards. Never paraphrase several guards into one line. | List every edit the block forbade and find each surviving sentence. `cleanup_check.py` prints `CLN-02 review` items and never fails on them | MUST |\n| CLN-03 | Leave every non-prose line byte-identical: code, interface doc text, tool directives, licence headers, fenced code and doctests. A Python `Example:`\u002F`Examples:` section and a reST `::` literal block are frozen the same way as fenced code. A Python file that parsed at the base still parses. | `cleanup_check.py`, then the repo's own build, doc, doctest and lint gate | MUST |\n| CLN-04 | Removed prose is gone: it never reappears at 80% token overlap or more in the file's other comments, a declared relocation lands in its record, and a pointer never sits beside the paraphrase it replaced. An added record pointer names a file the block named before the edit, a `--relocation` record, or a `--cites` record that already holds the removed argument. Every input comes from the diff, never from a list the editing agent wrote. | `cleanup_check.py`, with `--relocation` and `--cites` once per record; a human confirms each `--cites` record | MUST |\n| CLN-05 | Touch no test file or in-file test region, lock or manifest, generated or golden file, or non-source path other than a declared record that is new or only grows. | `cleanup_check.py`. `RECORD=docs\u002Fadr\u002F0042-example-record.md; git diff --numstat \"$BASE\" -- \"$RECORD\"` shows 0 deleted lines | MUST |\n| CLN-06 | Re-check every shortened guard in a fresh read-only session: the unled question first, scored for mechanism plus consequence, then the led question naming the recorded breaking edit. A `may-change` after a strong unled answer fails. | Step 9, with [references\u002Freason-recheck.md](references\u002Freason-recheck.md) | SHOULD; required for every shortened guard in a sweep |\n| CLN-07 | Shrink a guard to a one-line pointer only when every breaking edit it names has an owner that failed on that edit in a scratch copy: an enabled lint, a scoped `deny`, a type check or any test, named in the block or not. The pointer names every test that failed and none that stayed green. An edit with no proven owner keeps its mechanism, edit and consequence. | Step 5's planted-edit run, once per owner and edit | MUST |\n| CLN-08 | Clean only the files the change already touches. A sweep runs one file per commit and skips any file another branch or an open pull request has in flight, checked before starting it and again before merge. | The two commands under [Scope](#scope) print nothing | SHOULD |\n\n## Report\n\nReturn, per file:\n\n- over-cap lines before and after, from `--over-cap`;\n- blocks deleted, guards shortened (each with its owner proof or re-check level),\n  and records that received text;\n- every `CLN-02 review` item, and how you resolved it;\n- every `--cites` record, for a human to confirm it holds the removed argument;\n- gate failures already red at `BASE`, and files whose in-flight check was\n  unavailable;\n- what you left for another change: interface leaks, test-doc and rule\n  candidates, dead pointers, local-rule conflicts, commented-out code, a clause\n  the code contradicts, bare IDs in tests with the file's `bare-id-test` count,\n  and any guard whose consequence you could not state.\n\n## MUST rows this procedure surfaces\n\nRestated so a cleanup run without the rule loaded still reports them with the\nright ID. [Cleanup rules](#cleanup-rules) and the installed rule hold the text\nand full verification.\n\n| # | Finding | Rule |\n|---|---|---|\n| 1 | A block deleted without being positively identified as narration, tautology, a banner, a bare ID or unquantified pure provenance | CLN-01 |\n| 2 | A recogniser-flagged block, a `SAFETY:` label, a deferred-shortcut marker, or a comment another rule mandates, removed whole with no replacement | CLN-01, GRD-06 |\n| 3 | A block over 3 lines routed whole instead of clause by clause | RTE-01 |\n| 4 | A guard block over 5 lines shortened without a clause split, or several guards paraphrased into one line | CLN-02 |\n| 5 | A guard cut below constraint plus consequence | GRD-01 |\n| 6 | A non-prose line changed: code, interface text, a directive, a licence header, fenced code or a doctest | CLN-03 |\n| 7 | Removed prose survives elsewhere in the file, a declared relocation did not land, or a pointer sits beside the paraphrase it replaced | CLN-04 |\n| 8 | The diff touches a test or test region, a lock or manifest, a generated or golden file, or a non-source path other than a declared record that only grows | CLN-05 |\n| 9 | A guard shrunk to a pointer without a failing planted-edit run for every breaking edit, or a pointer naming a test that stayed green | CLN-07, GRD-07, RTE-03 |\n| 10 | A file-qualified pointer dropped without the same target reappearing | GRD-11 |\n| 11 | A record pointer added to a file the block did not name before the edit, that is neither a `--relocation` nor a `--cites` record | CLN-04, LNK-05 |\n| 12 | A pointer to a commit, a branch, a backup ref or a gitignored path | RTE-02 |\n| 13 | A record pointer that does not resolve to a tracked file | LNK-02 |\n\n## What agents get wrong\n\nRanked, most frequent first. Each mode, its tell and its catch are in\n[references\u002Ffailure-modes.md](references\u002Ffailure-modes.md).\n\n1. **Collapsing a guard bundle into one paraphrase**, dropping the consequence\n   clause first.\n2. **Deleting by category or length:** \"long means essay\", \"past tense means\n   history\", \"`Step N:` means narration\".\n3. **Crediting an owner by its name.** A test named after the constraint often\n   stays green on the breaking edit.\n4. **Adding the pointer and keeping the essay** beside it.\n5. **Reporting success from its own reading** instead of the check and the\n   re-check.\n6. **Incidental edits outside prose:** a help string, a directive, a doctest.\n\n## References\n\n| Read | When |\n|---|---|\n| [references\u002Fdecision-list.md](references\u002Fdecision-list.md) | Step 3 and 4: tagging a clause, writing a guard, choosing the register, meeting a cap |\n| [references\u002Freason-recheck.md](references\u002Freason-recheck.md) | Step 9: the unled and led prompts, the session command, the scoring levels |\n| [references\u002Ffailure-modes.md](references\u002Ffailure-modes.md) | Before a sweep, or when a check fails and the cause is unclear |\n",{"name":5,"license":14,"metadata":23,"description":7},{"summary":24,"keywords":25,"repository":26},"Shortens comments clause by clause, guard first, gated by a structural diff check and a cold reason re-check for every shortened guard","comments,code-comments,comment-cleanup,comment-density,doc-comments,docstrings,rustdoc,jsdoc,tsdoc,godoc,javadoc,kdoc,guards,why-comments,essay-comments,decision-records,adr,plan-ids,process-ids,pointers,ratchet,length-caps,refactor,code-docs","https:\u002F\u002Fgithub.com\u002Focx-sh\u002Fgrimoire-lore","main","ec018c25128e4b5b2e08679288e9e9153085830a",".agents\u002Fskills\u002Fcode-docs-cleanup",1,"https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire","https:\u002F\u002Fgrimoire.rs","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs","2026-11-14 09:47:24",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add grimoire-rs\u002Fgrimoire --skill code-docs-cleanup",{"tool":41,"command":42},"bunx","bunx skills add grimoire-rs\u002Fgrimoire --skill code-docs-cleanup",{"tool":44,"command":45},"pnpm","pnpm dlx skills add grimoire-rs\u002Fgrimoire --skill code-docs-cleanup","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcode-docs-cleanup\u002FSKILL.md",true,[49,55,59],{"path":50,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fdecision-list.md","REFERENCE","参考文档",10282,"https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcode-docs-cleanup\u002Freferences\u002Fdecision-list.md",{"path":56,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Ffailure-modes.md",9502,"https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcode-docs-cleanup\u002Freferences\u002Ffailure-modes.md",{"path":60,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Freason-recheck.md",9933,"https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcode-docs-cleanup\u002Freferences\u002Freason-recheck.md",[64,72,79,86,93,100],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":71},"01M78R7R0RQWY8BC0AQSB3E6NX","rca","Use when a bug ticket, GitHub issue or error report needs a root cause analysis before code is touched — \"is this a bug\", \"why does this fail\". Read-only. Gives a verdict (bug or not-a-bug kind), file:line evidence, ruled-out hypotheses, other affected sites, fix direction and size. A ticket, not a diff (hex-review).","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frca\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":71},"01M78R7JY3CY2XDNTB330GXTJK","fix","Use when a bug ticket or GitHub issue should go from report to an approved fix plan — \"plan a fix\", \"fix this issue\". Root-causes it via rca, then plans in plan mode with the failing regression test first. Routes to hex-plan instead when the fix is large or moves an interface contract.","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ffix\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":18},"01M72XYVY9FGB38MZDJ0QFFMCC","p9-skill","Principle 9 differential fixture skill (v2).","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002Ftest\u002Ftools\u002Fp9_fixtures\u002Fv2\u002Fskills\u002Fp9-skill\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":18},"01M72XYT3PPTXEFWCR8H4GWKEG","p9-member","Bundle member skill for the Principle 9 fixture (v2).","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002Ftest\u002Ftools\u002Fp9_fixtures\u002Fv2\u002Fskills\u002Fp9-member\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":18},"01M72XYRWQWZ4BD0367QWG96TB","p9-hookish","Hook-free skill carrying an ignored hook.toml (v2).","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002Ftest\u002Ftools\u002Fp9_fixtures\u002Fv2\u002Fskills\u002Fp9-hookish\u002FSKILL.md",[],[],{"skillNo":101,"name":81,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":18},"01M72XYPDXXK5C6ZDD5BS2N6HS","Principle 9 differential fixture skill (v1).","https:\u002F\u002Fgithub.com\u002Fgrimoire-rs\u002Fgrimoire\u002Fblob\u002Fmain\u002Ftest\u002Ftools\u002Fp9_fixtures\u002Fv1\u002Fskills\u002Fp9-skill\u002FSKILL.md",[],[]]