Documentation sync (docs-sync)
Stale docs pass every automated gate. The link checker only sees broken links; the test suite
never reads prose. So this is enforced as a procedure.
Principles
- Verify claim by claim. Do not skim for readability. Extract the checkable claims a
sentence makes — paths, versions, numbers, behavior, defaults — and check each against reality.
- Never edit without evidence. A
file:line, a command's output, or an official-docs URL.
What you could not confirm gets marked "unverified" rather than deleted — deleting it
destroys the information.
- No optimistic wording. If something only partly works, do not write that it "works". State
what holds and what does not.
Procedure
1. Extract the change surface
git log --oneline <last-doc-commit>..HEAD
git diff --stat <last-doc-commit>..HEAD
Keep only what documentation can be wrong about: CLI flags and defaults, paths, generated
artifacts, versions, thresholds, gate behavior, support scope.
2. Collect the checkable claims
Targets: README*, AGENTS.md, CLAUDE.md, per-directory README.md, skill/agent docs.
grep -rn '`[^`]*/`\|version\|default\|v[0-9]\+\.[0-9]' README*.md docs/ 2>/dev/null
What goes stale fastest: directory-tree blocks (new artifacts missing), version strings,
"it automatically ..." behavior claims, support matrices.
3. Check each claim
| Claim type |
How to verify |
| Path / file exists |
ls / find — against the generated output, not the source tree |
| CLI flag or default |
Run <cmd> --help. The output is the evidence, never another doc |
| Tool version |
<cmd> --version, and record the measurement date |
| Behavior ("auto-loads") |
The tool's official-docs URL. If none exists, say "no documented basis" |
| Numbers / thresholds |
grep the code, or measure the real artifact (wc -c, ...) |
| Gate behavior |
Actually run it and check the exit code |
4. Update parallel-language and overlay files together (required)
Updating one side leaves the others stale, and no gate catches it.
ls README*.md # every language README
ls presets/lang-en/ 2>/dev/null # is there a language overlay?
- Touching one README means touching every language edition in the same commit — in this
repository that is
README.md (English), README.ko.md, README.zh.md, README.ja.md.
- Touching a
.claude/** base file means touching its presets/lang-en/ counterpart too.
- These are not translations but per-language editions of the same facts — numbers, versions,
paths, and table structure stay identical.
- Blanket replacement breaks across languages.
grep -n the target text in each file first.
5. Run the gates
python3 .claude/scripts/knowledge_graph.py --check # expect 0 broken links
Run the test suite even for docs-only changes — a command or path quoted in the docs that no
longer matches the tests will surface here.
6. Report
List each correction as before → after + evidence. Do not collapse it into "updated the
README". Report what you left marked "unverified" as well.
Done when
- Every checkable claim has evidence or an explicit "unverified" marker
- Parallel-language and overlay counterparts are in the same commit
- Link checker reports 0 broken, test suite passes
Learned warnings
- Deleting a stale statement breaks the trail of why it disappeared — prefer marking it
"unverified" with the measurement date.
- Directory-tree blocks go stale most often. A commit that adds an artifact but not the tree entry
slips past the link checker, because tree entries are code-block text rather than links.
1---2name: docs-sync-23description: Bring documentation back in line with the code after changes to behavior, paths, versions, or generated output. Use on "update the docs", "refresh the README", "docs are stale", and right before opening a PR that changed any of those. Checks each documented claim against the actual code, command output, or official docs, and updates the parallel-language files together.4---56# Documentation sync (docs-sync)78Stale docs pass every automated gate. The link checker only sees broken links; the test suite9never reads prose. So this is enforced as a procedure.1011## Principles1213- **Verify claim by claim.** Do not skim for readability. Extract the **checkable claims** a14 sentence makes — paths, versions, numbers, behavior, defaults — and check each against reality.15- **Never edit without evidence.** A `file:line`, a command's output, or an official-docs URL.16 What you could not confirm gets marked **"unverified"** rather than deleted — deleting it17 destroys the information.18- **No optimistic wording.** If something only partly works, do not write that it "works". State19 what holds and what does not.2021## Procedure2223### 1. Extract the change surface2425```bash26git log --oneline <last-doc-commit>..HEAD27git diff --stat <last-doc-commit>..HEAD28```2930Keep only what documentation can be wrong about: CLI flags and defaults, paths, generated31artifacts, versions, thresholds, gate behavior, support scope.3233### 2. Collect the checkable claims3435Targets: `README*`, `AGENTS.md`, `CLAUDE.md`, per-directory `README.md`, skill/agent docs.3637```bash38grep -rn '`[^`]*/`\|version\|default\|v[0-9]\+\.[0-9]' README*.md docs/ 2>/dev/null39```4041What goes stale fastest: **directory-tree blocks** (new artifacts missing), **version strings**,42**"it automatically ..." behavior claims**, **support matrices**.4344### 3. Check each claim4546| Claim type | How to verify |47|---|---|48| Path / file exists | `ls` / `find` — against the generated output, not the source tree |49| CLI flag or default | Run `<cmd> --help`. The output is the evidence, never another doc |50| Tool version | `<cmd> --version`, and **record the measurement date** |51| Behavior ("auto-loads") | The tool's **official-docs URL**. If none exists, say "no documented basis" |52| Numbers / thresholds | grep the code, or measure the real artifact (`wc -c`, ...) |53| Gate behavior | Actually run it and check the exit code |5455### 4. Update parallel-language and overlay files together (required)5657Updating one side leaves the others stale, and **no gate catches it.**5859```bash60ls README*.md # every language README61ls presets/lang-en/ 2>/dev/null # is there a language overlay?62```6364- Touching one README means touching every language edition in the **same commit** — in this65 repository that is `README.md` (English), `README.ko.md`, `README.zh.md`, `README.ja.md`.66- Touching a `.claude/**` base file means touching its `presets/lang-en/` counterpart too.67- These are not translations but **per-language editions of the same facts** — numbers, versions,68 paths, and table structure stay identical.69- Blanket replacement breaks across languages. `grep -n` the target text in each file first.7071### 5. Run the gates7273```bash74python3 .claude/scripts/knowledge_graph.py --check # expect 0 broken links75```7677Run the test suite even for docs-only changes — a command or path quoted in the docs that no78longer matches the tests will surface here.7980### 6. Report8182List each correction as **`before → after + evidence`**. Do not collapse it into "updated the83README". Report what you left marked "unverified" as well.8485## Done when8687- Every checkable claim has evidence or an explicit "unverified" marker88- Parallel-language and overlay counterparts are in the same commit89- Link checker reports 0 broken, test suite passes9091## Learned warnings9293- Deleting a stale statement breaks the trail of why it disappeared — prefer marking it94 "unverified" with the measurement date.95- Directory-tree blocks go stale most often. A commit that adds an artifact but not the tree entry96 slips past the link checker, because tree entries are code-block text rather than links.
LeeYudok