doc-synclisted

# Doc sync Documentation does not rot gradually. It becomes false at a specific commit, and then stays false until someone notices — usually a new person, who trusts it, and loses an afternoon. This is the pass that runs *after* a change: find what the change falsified, and fix exactly that. The `documenter` agent writes docs from scratch; this keeps existing ones true. ## 1. Find what the change falsified Start from the diff, not from the docs. ```sh git diff --name-only <base>..HEAD ``` For every renamed, removed or signature-changed thing, grep the docs for it: ```sh rg -n '<old-name>|<old-flag>|<old-path>' --glob '*.md' --glob '*.rst' .claude/tools/selfcheck.sh # in a .claude config: names docs claim but that are gone ``` The five that go stale first, in order of how often: 1. **Command examples** — a renamed flag, a changed default, a moved path. 2. **Output samples** — pasted once, never re-run, now showing columns that no longer exist. 3. **Config keys** — documented after being renamed. 4. **Cross-references** — a link to a file that moved or a section that was retitled. 5. **Counts and lists** — "the six tools", now seven. This one is invisible and constant. ## 2. Verify before you rewrite Do not fix a doc from what you assume the new behaviour is. Run it. ```sh .claude/tools/watch.sh --idle 60 -- <the documented command> ``` Paste the **real** output, unglamorous parts included. Output trimmed to look cleaner than reality is a small lie tha