Docs Cleaner Documentation goes wrong in recurring ways, and they need different work. It rots. Something changed — a port, a path, a procedure, a decision — and the docs still describe the old world. The field's name for this is documentation rot or version drift : artifacts fall out of sync one at a time until people stop trusting the set. It sprawls. The same topic accumulates three files, each partly right, none authoritative. They trace to one root cause: a fact was written down in more places than it was defined. Everything below follows from fixing that. Core principle (governs both mo…

...';\n# \"\\n\" inside double quotes is a literal backslash-n and matches nothing (measured).\nrg -U -F

Docs Cleaner Documentation goes wrong in recurring ways, and they need different work. It rots. Something changed — a port, a path, a procedure, a decision — and the docs still describe the old world. The field's name for this is documentation rot or version drift : artifacts fall out of sync one at a time until people stop trusting the set. It sprawls. The same topic accumulates three files, each partly right, none authoritative. They trace to one root cause: a fact was written down in more places than it was defined. Everything below follows from fixing that. Core principle (governs both mo…

first line of the fact\\nsecond line of it' \"$ROOT\" --no-ignore --hidden -g '!.git'\n```\n\n`-g '!.git'` is not optional once `--no-ignore` is on: without it the search reports hits in\n`.git/COMMIT_EDITMSG` and `.git/logs/HEAD` — the commit messages that *describe* your change\n— as surviving copies. Those can never be \"cleaned\", so a check that counts them trains you\nto wave off count mismatches, which disarms it for the real ones. `--no-ignore` also\nrestores `node_modules/` and other vendored trees; exclude those the same way when they\nappear.\n\n**Write down the expected counts before you search, not after.** A count you decide once\nyou have seen the output cannot fail. State which files should still contain the value and\nwhich should not, then run:\n\n```bash\nrg -U -F --count-matches \"the old value\" \"$ROOT\" --no-ignore --hidden -g '!.git'\nrg -U -F --count-matches \"the new value\" \"$ROOT\" --no-ignore --hidden -g '!.git'\n```\n\nCompare each result against your list as **set equality**, in both directions: a file that\nappears and should not is a leftover, and a file on your list that does *not* appear is\nequally a failure — `--count-matches` omits zero-match files from its output entirely, so a\ndocument that was supposed to receive the new value and silently did not looks exactly like\na clean run.\n\nWhat makes this check honest:\n\n- **The old value does not always go to zero.** A changelog entry, a decision log, or an\n \"as of \u003cdate> this was X\" sentence records history and legitimately keeps the old value\n (Drift Test question 3). Deleting those so a count reaches zero destroys an audit trail\n in order to satisfy a check. Name the historical files in advance; anything *outside*\n that list is a leftover.\n- **`--no-ignore --hidden` is on purpose, and they are not the same flag.** By default `rg`\n skips both VCS-ignored files *and* hidden ones. `--no-ignore` only restores the first\n group; without `--hidden` the search still never opens `.github/`, which is where\n contributing guides, issue templates, and workflows full of documented commands live\n (measured: adding `--hidden` took a sample search from 4 files to 6). A convergence gate\n that cannot see those directories goes green over a surviving stale copy. Include them\n and judge the extra hits rather than assuming they do not matter.\n\n**Calibrate before you trust a zero — whichever tool you used.** A search returning nothing\nhas two causes: the fact is gone, or the command is wrong. They look identical. Before\nreporting \"no remaining copies\", run the same command shape against a string you *know* is\npresent. If that also returns nothing, the instrument is broken, not the docs. This is the\ndirect antidote to the pathless-`rg` failure above, and it costs one line.\n\n### Without ripgrep\n\n`git grep -nF \"fact\" -- .` works in any git repo and is one implementation across platforms\n(unlike `grep`, whose recursion and symlink behavior differ between BSD, GNU, and drop-in\nreplacements). It has these limits, all measured, all of which produce a confident wrong\nanswer rather than an error:\n\n> **It searches tracked files only.** The consolidated document you just wrote in Mode 2 is\n> new and untracked — so a preservation check run through `git grep` reports its content\n> missing and you \"restore\" what was never lost. `git add` it first, or read that file\n> directly.\n\n> **`-F` with a multi-line string silently degrades to matching the lines independently.**\n> A file that kept only the first line of a two-line fact still reports a hit — so a lossy\n> move gets certified as \"the content is still there\", the one error a preservation check\n> exists to catch. True of both `grep` and `git grep`.\n\nWith neither tool available, a contiguous check runs anywhere Python does:\n\n```bash\npython3 -c 'import sys, pathlib\n# .rstrip(\"\\n\") matters: your editor adds a trailing newline to needle.txt, and a fact\n# sitting at a file'\"'\"'s end has none — without the strip, that copy is silently missed.\nneedle = pathlib.Path(sys.argv[1]).read_text(encoding=\"utf-8\").rstrip(\"\\n\")\nfor f in sys.argv[2:]:\n n = pathlib.Path(f).read_text(encoding=\"utf-8\").count(needle)\n if n: print(f, n)' needle.txt doc1.md doc2.md\n```\n\n### Updating references to a file you moved or deleted\n\nFor a split entry or renamed section, the\n[delivery-entry replay](references/delivery-entry-replay.md) supplies a bounded stale-anchor\ncontrol and repaired-entry check. Read bare prose section references against the actual\nheading; link-checker success does not validate prose that it never parsed as a link.\n\nSearching the bare filename finds some inbound links and misses the rest, then reports\n\"verified\". A file is referenced in more shapes than one:\n\n```bash\nBASE=old-doc # filename without extension\nrg -n -F -e \"$BASE.md\" -e \"[[$BASE\" -e \"($BASE\" -e \"/$BASE\" \"$ROOT\" --no-ignore --hidden -g '!.git'\n```\n\nThat covers Markdown links, wiki-style `[[old-doc]]`, bare paths, and imports. What it will\nnot do for you:\n\n- **Relative paths break when a file changes directory depth.** `../guide.md` from one\n level is `../../guide.md` from another. Grepping the filename finds the line; whether the\n path still resolves is a separate question, per link.\n- **\"Verify no broken links\" has two directions, and Phase 4 only owes you one of them.**\n *Inbound* — \"does anything still point at what I removed?\" — is what consolidation can\n break, and the search above answers it. Do that one; it is the step's actual obligation.\n\n *Outbound* — \"does every link in these files still resolve?\" — is a general docs-QA job,\n not something to hand-roll here. Use a real link checker:\n\n ```bash\n lychee --offline --root-dir \"$PWD\" docs/ # local paths only, no network\n lychee docs/ # also checks external URLs (slow, fails for unrelated reasons)\n ```\n\n `--root-dir` is not optional if the docs use root-relative links (`/docs/x.md` — the\n normal style under mkdocs, Docusaurus, GitHub Pages): without it lychee reports every one\n of them as an error, which is the same false-flagging the paragraph below says to avoid.\n Anchors (`x.md#section`) are not checked unless you add `--include-fragments`.\n\n **`0 Total` is not a pass — calibrate before you believe it.** Measured (lychee 0.24.2): a\n path that does not exist fails loudly with exit 1, but a directory that exists and holds\n no Markdown prints `🔍 0 Total … ✅ 0 OK 🚫 0 Errors` and **exits 0** — identical to a\n clean run. Point it one directory too high or too deep and you get a green check that\n looked at nothing. Read the `Total` count: if it is 0, either confirm the files genuinely\n contain no links, or you searched the wrong place. (Files whose links are all in inline\n code or fenced blocks legitimately total 0 — lychee skips both, correctly.)\n\n `lychee` (`brew install lychee` / `cargo install lychee`) handles Markdown link forms\n that a shell pipeline does not: angle-bracket links `[x](\u003cmy file.md>)`, titled links\n `[x](y.md \"Title\")`, nested parens, reference-style `[x][ref]`, and links inside fenced\n code blocks all break a regex-and-`test -e` approach, in both directions — silently\n missing real breakage and falsely flagging valid links. If no link checker is available,\n say the outbound check was not run rather than substituting a hand-rolled one.\n\n A checker validates only the links and fragments it parses. Its heading, anchor and\n autolink rules may differ from the intended reader's host. For example, an emoji heading\n containing a variation selector (VS16), or a bare email beside punctuation, can produce\n a checker error even when the host's permalink or `mailto:` target works. These are\n parser-compatibility examples, not a portable heading-slug algorithm.\n\n Before calling a reported link broken or changing it, inspect the **exact Markdown in\n the intended reader host**: follow the rendered heading/permalink or inspect the email's\n actual `mailto:` target. Classify a confirmed missing or mismatched target as a real\n broken link; classify a working host target with a checker error as parser portability.\n If that host cannot be checked, keep reader resolution unverified rather than inferring\n it from the checker. For a compatibility repair, preserve the visible label and contact\n identity, then verify both the checker result and the actual reader target. Do not\n remove a useful entry or change its intended destination merely to silence a diagnostic.\n\n### Preservation check (Mode 2)\n\nThe old form of this check was a list of things to tick off — \"essential procedures\npreserved\", \"gotchas preserved\". The person who deleted them ticks the boxes, so it can\nnever fail. Replace self-assessment with evidence: name each specific item and show where it\nnow lives. The categories further down are a checklist of *kinds* to sweep for, not the unit\nthe evidence is counted in.\n\nUse the list you built in Phase 4 step 1 — one entry per load-bearing item, written before\nthe rewrite. (Missed that step? Phase 4 step 7 says how to recover the sources from git and\nwhich ref to use.) What you must never do is take the expected strings from the consolidated\nfile: that only proves the file matches itself.\n\n**The method depends on the disposition, and using the wrong one produces a false\ndeletion report.** A section marked Keep should survive word for word; a section marked\nCondense was *supposed* to be rewritten, so a verbatim search for its old sentence\ncorrectly returns nothing — that is the condensation working, not content loss.\n\n| Disposition | How to show it survived |\n|---|---|\n| **Keep**, carried over as-is | Per saved item: `rg -U -F \"\u003csaved distinctive line>\" \u003cconsolidated file>` → a hit |\n| **Keep**, merged with another section — **only if the merge was recorded before the rewrite** (in the Phase 3 plan or the step-1 inventory) | A verbatim search will miss — merging two sections that state the same constraint in different words produces a third phrasing, and that is the point of Mode 2. Use the Condense method below. **Do not paste the original sentences back in to make the search go green**: that reinstates the duplication you were removing. |\n\n**Which of those two rows applies is decided before the rewrite, never at check time.** If you\ncannot point at a plan or inventory line saying this section was being merged, the row above\napplies and a miss is a miss. This is not bookkeeping: letting the agent whose search just\nfailed pick which row it is graded by converts a hard verbatim gate into a soft one, and it\nconverts it *only in the cases where it just caught something*. The failure it lets through\nis not merging — it is a plain Keep section quietly reworded during the rewrite, its\nconsequence clause dropped, relabelled \"merged\" so the softer method returns a hit on the\nweakened sentence.\n| **Condense** | Per saved claim (each constraint, number, condition, warning): quote the line in the consolidated file that carries it. A claim you cannot point to was dropped, whatever the prose length says. |\n| **Delete** | Per saved item: where the surviving copy is, or — if there is none — the reason it is going. \"It looked redundant\" is not a reason; naming what was in it is. |\n\nThe categories below are a **recall prompt, not the unit** — they exist so you notice a class\nyou forgot, and each one still resolves to per-item evidence from the table above. Ticked\ncategories are not per-item evidence.\n\n| Category (applies to Keep and Condense alike) | Evidence to produce |\n|---|---|\n| Essential procedures (setup, configuration) | per the disposition row above |\n| Key constraints and gotchas | same, one per gotcha — these are the load-bearing claims a condensation most often drops |\n| Troubleshooting guidance | same |\n| Technical debt / roadmap items | same |\n| External links and references | each URL saved from a **Keep or Condense** section appears verbatim in the new file (string presence, not an HTTP request). URLs survive condensation intact or they were dropped — there is no \"shorter URL\". URLs saved from a Delete section follow the Delete row instead: say where the link survives, or that it is going and why. **Do not paste one back into the consolidated file to make this line green** — that reinstates content you decided to drop |\n| Debug tips and code snippets | same; code is verbatim even inside a condensed section |\n\n**A hit proves the string is in the file; it does not prove it is in the right place.** A\nstaging-only warning that landed under a \"Production\" heading, or a constraint moved out\nfrom under the conditional that scoped it, passes this check while now saying something\nfalse. When an item's meaning depends on where it sits, read the surrounding lines rather\nthan stopping at the match — the same reason a lossy multi-line move can be certified as\n\"still there\".\n\nAnything you cannot produce a hit for was not preserved — it was deleted. That may be the\nright call, but it belongs in the report as a deletion, not inside a checkmark.\n\n**A zero-deletion outcome is a legitimate result.** If the value analysis says every\nsection earns its place, report \"nothing to consolidate\" and stop. Line reduction\nis never a target — an agent that deletes something in order to\nhave a number to report has inverted the whole point.\n\n---\n\n## What to report\n\nState each of these explicitly. Silence on any of them reads as \"nothing to say\", which is\nrarely true:\n\n1. **Inconsistencies found** — what disagreed with what\n2. **Authoritative source used** — which file you treated as defining each fact, and on\n which ground you picked it when more than one looked declarative\n3. **Files changed and why** — one line each\n4. **Derived values and redundant references removed** — where each one was, and why it\n qualified as derived rather than as a fact worth keeping\n5. **Search evidence** — the commands you ran and their counts, so every claim above is\n checkable rather than asserted. This is the same artifact listed under *Output\n artifacts*; both lists mean one report, not two.\n6. **The corrected procedure**, end to end, if a procedure changed\n7. **What is still unresolved** — untouched exceptions, known-stale areas out of scope,\n risks you could not close\n\nIn Mode 2 this report also carries the value-analysis table and the before/after metrics.\n\nPoint 4 is the one that gets dropped, and it is the one that compounds: naming a removed\nderived value teaches the reader why it should not come back.\n\n---\n\n## Anti-patterns\n\n| Pattern | Problem | Instead |\n|---|---|---|\n| Blind deletion | Loses information | Section-by-section value analysis first |\n| Keeping everything | No reduction achieved | Apply the value criteria strictly |\n| Multiple sources of truth | Guaranteed future divergence | One authoritative location, others link |\n| Orphaned references | Broken links | Update every reference after moving content |\n| Persisting a derived value | Goes stale silently; nothing flags it | Drift Test question 1 — do not write it |\n| Linking a derived value | Scaffolding that also goes stale, plus false confidence the two are aligned | Same — the value should not exist |\n| Patching a doc whose premise died | Internally consistent, globally wrong | Archive it (disposition, step 4) |\n| Updating the obvious occurrence only | Quiet copies survive and contradict it later | Search before editing (step 5) |\n| Documenting unimplemented wishes | Doc and reality diverge from day one | Follow step 3: repair only established, already-authorized behavior; otherwise report the disagreement |\n| Unbounded \"while I'm here\" sweeps | Unreviewable diff; real changes get lost in it | Bounded cleanup (step 6) |\n\n---\n\n## Output artifacts\n\nA successful pass produces:\n\n1. **The corrected documents** — with a single authoritative location per fact\n2. **Value analysis** (Mode 2) — section-by-section justification\n3. **Before/after metrics** (Mode 2) — lines reduced, value preserved\n4. **Search evidence** — the commands run and their counts, so the claims are checkable\n5. **Updated references** — a pointer to the new location exists in the main doc or\n README, and every pointer to moved content resolves\n\n## Next Step\n\nAfter the docs are consistent, the natural follow-ons:\n\n```\nDocs are now consistent — [N] files updated, [M] derived values removed.\n\nOptions:\nA) Convert the recurring parts into a project rule — if the same drift keeps\n recurring, the fix is a rule in the project's main doc, not another cleanup pass\nB) Render or publish the result — if these docs have a build/publish step\nC) Nothing further — the docs are the deliverable\n```","attachment_filenames":["references/delivery-entry-replay.md","references/value_analysis_template.md"],"attachments":[{"filename":"references/delivery-entry-replay.md","content":"---\nname: delivery-entry-replay\ndescription: >-\n Replay project instruction links after splitting a Skill entry or renaming a\n procedure heading, with stale-anchor controls and actual-consumer readback.\n---\n\n# Delivery-entry replay\n\nUse this after moving a procedure out of a Skill entry or renaming its heading. The\nacceptance question is whether a new reader starting at the project's instruction file\nreaches the current procedure and its conditions. A valid Skill package, an existing\nreference file, or a link to a different surviving section cannot answer that question.\n\n## Scope and source\n\nStart with the changed procedure, its defining file, and the consuming `CLAUDE.md` /\n`AGENTS.md` entry. Inspect any directly affected `SKILL.md` pointer and invocation examples.\nApply [Mode 1](../SKILL.md#mode-1--post-change-governance) to their disposition and facts;\ndo not create another permanent routing inventory.\n\nRead the destination's actual heading and scoped instructions. Bare prose such as\n`SKILL.md § Delivery status` needs this read: it is not a Markdown link and lychee will\nnot check it. When it is navigation, replace it with a resolvable file-and-fragment link.\nFor a moved definition, link to that definition, not a new intermediate index that\nrestates it. Remove hand-maintained heading lists or counts encountered in files already\nbeing edited under the [Drift Test](../SKILL.md#the-drift-test-the-core-of-both-modes).\n\n## Calibrate the navigation check\n\nThis synthetic example models an entry split: the procedure survives in a reference,\nwhile the old instruction-file anchor points at a heading removed from `SKILL.md`.\nIt uses bash on macOS/Linux and an installed lychee with offline fragment checking.\nThe fixture is local and contains no credentials or private project material.\nIts reference path is created by the recipe inside that fixture, not shipped with\nthis Skill. A bundle-path warning about it is resolved by inspecting and replaying\nthe fixture; do not create a package-local copy just to silence the diagnostic.\n\n```bash\nset -eu\nfixture_root=$(mktemp -d)\nmkdir -p \"$fixture_root/references\"\ncat > \"$fixture_root/SKILL.md\" \u003c\u003c'MD'\n# Example Skill\n\nRead the [delivery procedure](references/workflow-details.md#delivery-status).\nMD\ncat > \"$fixture_root/references/workflow-details.md\" \u003c\u003c'MD'\n# Workflow details\n\n## Delivery status\n\nPublish only after the canonical document and its source registration agree.\nMD\ncat > \"$fixture_root/CLAUDE.md\" \u003c\u003c'MD'\n# Project instructions\n\nRead the [delivery procedure](SKILL.md#delivery-status).\nMD\n\n# First confirm the surviving procedure is reachable.\nlychee --offline --include-fragments --root-dir \"$fixture_root\" \"$fixture_root/SKILL.md\"\n\n# This must fail for the missing fragment, with a nonzero Total count.\nif lychee --offline --include-fragments --root-dir \"$fixture_root\" \"$fixture_root/CLAUDE.md\"; then\n echo 'negative control unexpectedly passed' >&2\n exit 1\nfi\n\ncat > \"$fixture_root/CLAUDE.md\" \u003c\u003c'MD'\n# Project instructions\n\nRead the [delivery procedure](references/workflow-details.md#delivery-status).\nMD\nlychee --offline --include-fragments --root-dir \"$fixture_root\" \"$fixture_root/CLAUDE.md\" \"$fixture_root/SKILL.md\"\nprintf 'Fixture retained at %s\\n' \"$fixture_root\"\n```\n\nInspect the failing result: it must identify the intended missing fragment, rather than\nan unrelated configuration or filesystem failure. The repaired result must check actual\nlinks and have no errors; `0 Total` supplies no navigation evidence. Run the same command\nshape on the real, explicitly named changed entry files. Then read the linked procedure\nto confirm its scope, ordering and completion criteria; lychee validates navigation,\nnot their correctness or whether an agent follows them. Retain the replay output with\nthe task evidence, not as a permanent count in the Skill.\n\n## Separate validity from warnings\n\nFor a Skill release, load `skill-creator` and read its\n**knowledge-skill-grounding** reference, section **Interpret validation warnings**,\nfor its validator invocation and result contract. Resolve that reference from the loaded\nSkill's own root, not a sibling repository layout. If the owner is unavailable, report\nthat validation stage as not checked; the local navigation replay remains independent.\nInspect warnings separately from\nstructural validity and the process exit status. A warning about a repository-level\nresource being interpreted as a bundled path needs its actual owner and root checked;\ndo not add a fake package-local copy or suppress the warning just to make the run green.\nRecheck the same affected input after repair and report the warning's disposition.\n\nRead back the repaired entry where the consumer loads it, including any installed\nsymlink or copied bundle. Source-file success cannot establish that an older installed\nentry has been updated. Reuse unchanged code-test evidence; this replay establishes\nnavigation and document alignment, not a new execution of the underlying operation.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5005,"content_sha256":"31ee5f0f48c1f13a364af5e31a8029156d55c3a7b6a4edaa0598d3b892d7f921"},{"filename":"references/value_analysis_template.md","content":"# Value Analysis Template\n\nUse this template for section-by-section documentation analysis.\n\n## Document Analysis Table\n\n| Section | Lines | Value | Reason |\n|---------|-------|-------|--------|\n| Example Section | 25 | Keep | Contains unique troubleshooting steps not documented elsewhere |\n| Another Section | 40 | Delete | Duplicates content in CLAUDE.md |\n| Technical Details | 60 | Condense | Valuable but verbose; can be reduced to 15 lines |\n| Setup Instructions | 30 | Keep | Essential for onboarding |\n\n## Value Categories\n\n### Keep (Green)\n- Unique information not found elsewhere\n- Essential procedures (setup, troubleshooting, constraints)\n- Frequently referenced content\n- Technical debt / roadmap items\n\n### Condense (Yellow)\n- Valuable but overly verbose\n- Contains redundant examples\n- Can be expressed more concisely\n\n### Delete (Red)\n- Duplicates existing documentation\n- One-time material with no continuing reader and no moment attached to it — a pasted copy of\n a tool's `--help` text, a duplicated third-party quickstart. Note what this bullet's example\n is *not*: \"a pasted test run's output\" would be a **dated measurement**, which the carve-out\n below excludes — an example that its own exception swallows is worse than no example.\n **⚠️ Never a passage that records what was true at a moment** (changelog, decision log,\n incident timeline, dated measurement, postmortem). That class is the Drift Test's question\n 3; it may still be deleted, but only as a **named proposal to the owner with your reason**,\n never as a quiet Delete row. When you cannot tell, ask; do not resolve it by deleting.\n- Self-evident information (code already documents this)\n- Outdated or superseded content — **but \"superseded\" is a Delete only for content that was\n describing the current state.** A document whose *premise* is dead (the design notes for a\n cancelled system, a postmortem for a service since retired) is not stale current-state; it\n is the record of a decision, and it goes to **Archive / retire** — moved out of the\n reader's path, not destroyed. Without this split, the same dead-project postmortem gets\n Deleted by one reader for being superseded and Kept by another for being a record.\n\n## Before proposing deletions\n\nThese are observations to produce, not boxes to tick. A tick is written by the same party\nthat wants the deletion approved, so it can never come back negative; each line below asks\ninstead for something a reader could check.\n\n| Question | What to show |\n|---|---|\n| Which files hold related content? | The search boundary you used and the command that produced the file list |\n| Where do they overlap? | The heading → files-that-also-cover-it table |\n| What is unique to each? | Per file, the sections no other file covers |\n| Which location becomes authoritative? | The chosen file, and why that one |\n| What references will need updating? | The list of inbound references found, per file being removed |\n\n## Applying the Drift Test to a row\n\nRun the SKILL.md Drift Test over every row. It settles one of the two disposition questions\nand deliberately leaves the other to you.\n\n**It does decide \"this is a derived value\":** a section can be well-written, unique to this\nfile, and still not belong anywhere — if its content is computable from details recorded\nelsewhere (a count, a total, a restated summary), it is a derived value and the disposition\nis Delete regardless of quality.\n\n**It does not decide keep-or-delete for historical passages.** When question 3 fires — the\nrow records what was true at a moment — all it establishes is that no drift remedy applies:\ndo not recompute it, do not link it away, do not update it to the current value. The value\njudgment stays on this table, and if it comes out Delete, it goes to the owner as a named\nproposal with your reason rather than a quiet Delete row.\n\n## Output Format\n\nAfter analysis, produce:\n\n1. **Value Analysis Table** - Per-section breakdown with keep/condense/delete\n2. **Consolidation Plan** - Target structure with line count estimates\n3. **Before/After Comparison** - Total lines and percentage reduction\n4. **Preservation evidence** - One entry per load-bearing item (each gotcha, constraint,\n snippet, URL — not one per category), showing where that item now lives. Anything you\n cannot point to is a deletion and gets reported as one.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4385,"content_sha256":"f514010c28d54631351fe4bd72b8d4fc4a8a8e5d89d6d432b0179eef749878bc"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Docs Cleaner","type":"text"}]},{"type":"paragraph","content":[{"text":"Documentation goes wrong in recurring ways, and they need different work.","type":"text"}]},{"type":"paragraph","content":[{"text":"It rots.","type":"text","marks":[{"type":"strong"}]},{"text":" Something changed — a port, a path, a procedure, a decision — and the docs still describe the old world. The field's name for this is ","type":"text"},{"text":"documentation rot","type":"text","marks":[{"type":"em"}]},{"text":" or ","type":"text"},{"text":"version drift","type":"text","marks":[{"type":"em"}]},{"text":": artifacts fall out of sync one at a time until people stop trusting the set.","type":"text"}]},{"type":"paragraph","content":[{"text":"It sprawls.","type":"text","marks":[{"type":"strong"}]},{"text":" The same topic accumulates three files, each partly right, none authoritative.","type":"text"}]},{"type":"paragraph","content":[{"text":"They trace to one root cause: ","type":"text"},{"text":"a fact was written down in more places than it was defined.","type":"text","marks":[{"type":"strong"}]},{"text":" Everything below follows from fixing that.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core principle (governs both modes)","type":"text"}]},{"type":"paragraph","content":[{"text":"Critical evaluation before deletion. Never blindly delete.","type":"text","marks":[{"type":"strong"}]},{"text":" Analyze each section's unique value before proposing removal. The goal is reduction without information loss.","type":"text"}]},{"type":"paragraph","content":[{"text":"This governs every deletion-shaped action in this skill, not just consolidation: archiving a document, dropping a derived value, and removing a cross-reference are all deletions and all owe the same analysis first. \"It looked redundant\" is not that analysis.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Which mode are you in?","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The user said / the situation","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mode","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"I changed X\" / a diff exists / a procedure was updated","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1 — Post-change governance","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"which docs are now wrong\", \"check for stale commands/paths\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1 — Post-change governance","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"clean up the docs\", \"too many files on this\", \"merge these\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2 — Consolidation","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"A topic is spread over several files with no clear owner","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2 — Consolidation","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"They share the Drift Test below. When both apply, run Mode 1 first: consolidating docs that are ","type":"text"},{"text":"also","type":"text","marks":[{"type":"em"}]},{"text":" factually stale just produces one confidently wrong document.","type":"text"}]},{"type":"paragraph","content":[{"text":"A note on ","type":"text","marks":[{"type":"strong"}]},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" / ","type":"text","marks":[{"type":"strong"}]},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":":","type":"text","marks":[{"type":"strong"}]},{"text":" both modes apply to them like any other document — govern them after a change, consolidate them when they duplicate each other. The one job that belongs elsewhere is ","type":"text"},{"text":"restructuring a single oversized one","type":"text","marks":[{"type":"em"}]},{"text":" — pushing low-frequency detail down into references while keeping the top level lean. That is what daymade-claude-code's ","type":"text"},{"text":"claude-md-progressive-disclosurer","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill is built for; prefer it when the problem is size and layering rather than truth or duplication. If it is not available, Mode 2 still handles the file — you just do the value analysis by hand.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"The Drift Test (the core of both modes)","type":"text"}]},{"type":"paragraph","content":[{"text":"Before writing any value into a document — and when deciding whether an existing one earns its place — ask these questions ","type":"text"},{"text":"in order, and stop at the first hit","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"paragraph","content":[{"text":"1. Can this be computed from details already recorded here or in the authoritative source?","type":"text","marks":[{"type":"strong"}]},{"text":" → It is a ","type":"text"},{"text":"derived value","type":"text","marks":[{"type":"strong"}]},{"text":". Do not write it. Compute it when someone asks. Examples: a count (\"6 sections\", \"N groups covered\"), a total, a status summarizing rows in a table below it, \"last updated on\" when the log underneath already says.","type":"text"}]},{"type":"paragraph","content":[{"text":"When you remove one, repair the sentence rather than leaving a hole: \"the four checks below\" becomes \"the checks below\". Deleting the number and leaving dangling grammar is a different defect, not a fix.","type":"text"}]},{"type":"paragraph","content":[{"text":"Exception — generated navigation.","type":"text","marks":[{"type":"em"}]},{"text":" A table of contents restating the headings is a derived value by this test, and hand-maintained ones should indeed go. But leave it alone when it is produced by the docs toolchain at build time, or when the platform requires the marker to render navigation: those are computed on demand, which is what question 1 asks for. Check for a generator before deleting one.","type":"text"}]},{"type":"paragraph","content":[{"text":"2. Not computable, but the same fact is authoritatively defined somewhere else?","type":"text","marks":[{"type":"strong"}]},{"text":" → It is a ","type":"text"},{"text":"copy","type":"text","marks":[{"type":"strong"}]},{"text":". Link to that definition. Do not restate the value.","type":"text"}]},{"type":"paragraph","content":[{"text":"3. Neither derivable nor copied — it independently records what was true at a particular moment?","type":"text","marks":[{"type":"strong"}]},{"text":" → It may remain as an ","type":"text"},{"text":"atomic historical observation","type":"text","marks":[{"type":"strong"}]},{"text":": a dated change, original measurement, price observation or decision. Never replace its past value with a current value or a current-config link.","type":"text"}]},{"type":"paragraph","content":[{"text":"Apply the ordered test to each claim, including claims inside changelogs, postmortems and dated notes. A date does not exempt a locally derivable total, ratio or copied summary from questions 1 and 2. Remove that derived or copied restatement while preserving the independent event, measurement and causal context.","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, a dated upload-limit change records the change at that time; today's config is a different fact. A region-addition event survives removal of a total computable from its recorded historical region details. Do not recompute that old total using today's regions.","type":"text"}]},{"type":"paragraph","content":[{"text":"A unique historical atom that passes questions 1 and 2 is not a drift repair. Its content value still receives Mode 2's analysis under the existing authorization. When the evidence does not establish whether a claim is derivable, copied or independently observed, retain it as unresolved and report the gap; do not guess a basis for deletion. New approval is needed only when the intended action exceeds the authorization already given.","type":"text"}]},{"type":"paragraph","content":[{"text":"Linking only solves case 2.","type":"text","marks":[{"type":"strong"}]},{"text":" Pointing a link at a derived value is a category error: there is no single authoritative cell to point at, so the link becomes scaffolding that goes stale on its own ","type":"text"},{"text":"and","type":"text","marks":[{"type":"em"}]},{"text":" creates a false impression that the two places are aligned.","type":"text"}]},{"type":"paragraph","content":[{"text":"Why this ordering matters:","type":"text","marks":[{"type":"strong"}]},{"text":" the mature answer to drift in API documentation is \"generate it from the source, don't hand-copy it\" (OpenAPI/Swagger exist for exactly this reason). Question 1 is that same instinct applied to prose — the surest way to keep a number correct is for it not to be written down twice.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Position gives no exemption","type":"text"}]},{"type":"paragraph","content":[{"text":"A fact is a fact wherever it sits. All of these are body text for the purposes of the test above, and all of them are where stale values actually survive audits:","type":"text"}]},{"type":"paragraph","content":[{"text":"frontmatter · YAML/JSON metadata · parenthetical asides · a description column in an index table · checkbox state · introductory framing before the real content · cross-document footnotes · an extra column added to a table · commit-message-shaped notes left in prose","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What counts as a fact","type":"text"}]},{"type":"paragraph","content":[{"text":"Anything that changes over time and has an authoritative definition somewhere: numbers, status, ownership, relationships, classifications, rules, decision sources, dates, counts. Business rules count too — \"all quotes route through the finance lead\" is defined once and referenced, never restated in each downstream doc.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mode 1 — Post-change governance","type":"text"}]},{"type":"paragraph","content":[{"text":"Run these in order. The order is the point: fixing derived docs before establishing what is authoritative just multiplies the work.","type":"text"}]},{"type":"paragraph","content":[{"text":"1. Scope it from the change, not from the repo.","type":"text","marks":[{"type":"strong"}]},{"text":" Enumerate the ","type":"text"},{"text":"facts","type":"text","marks":[{"type":"em"}]},{"text":" this change altered — this port, this path, this procedure name, this default. That list is what bounds the work. ","type":"text"},{"text":"The list is bounded; the search for each item on it is not","type":"text","marks":[{"type":"strong"}]},{"text":" — a fact's quiet copies live precisely in files the change never touched, so each fact gets searched repo-wide in step 5. What is forbidden is the other thing: opening files to look for ","type":"text"},{"text":"unrelated","type":"text","marks":[{"type":"em"}]},{"text":" problems. An unbounded sweep is how a doc task turns into an unreviewable refactor.","type":"text"}]},{"type":"paragraph","content":[{"text":"2. Identify the authoritative source (SSOT) for each affected fact.","type":"text","marks":[{"type":"strong"}]},{"text":" Which file ","type":"text"},{"text":"defines","type":"text","marks":[{"type":"em"}]},{"text":" this port / path / procedure — as opposed to mentioning it? Update that first. Everything downstream either points at it or is derived from it.","type":"text"}]},{"type":"paragraph","content":[{"text":"When a procedure moves from a Skill entry into a reference, include its consuming ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" pointer in this scope. Use the ","type":"text"},{"text":"delivery-entry replay","type":"text","marks":[{"type":"link","attrs":{"href":"references/delivery-entry-replay.md","title":null}}]},{"text":" to check the old and repaired navigation against the actual destination; reachability alone does not establish that the destination still defines the required procedure.","type":"text"}]},{"type":"paragraph","content":[{"text":"The practical test for \"defines\" is ","type":"text"},{"text":"where a change has to be made for reality to change","type":"text","marks":[{"type":"strong"}]},{"text":": the file the deployment actually reads, the schema the code loads, the runbook a human follows step by step. A file that recites the value while explaining something else is mentioning it. When two files both look declarative, prefer, in order: the one a machine consumes over one only humans read; the one nearest the thing it describes; the one other docs already cite. Then say in your report which you picked and on which of those grounds — an arbitrary pick becomes permanent once step 2 points everything else at it, so it should be a stated decision rather than an accident of which file you opened first.","type":"text"}]},{"type":"paragraph","content":[{"text":"3. Resolve implementation disagreements from established intent and authorization.","type":"text","marks":[{"type":"strong"}]},{"text":" Treat code, scripts, config, and observed runs as evidence of current behavior, not as automatic authority over intended behavior. When a requirement, authoritative source, or test establishes the intended behavior and the user has already authorized the scoped implementation fix, repair and verify the implementation first, then update the docs to match. Keep that repair within the facts and files already authorized by the task.","type":"text"}]},{"type":"paragraph","content":[{"text":"When intended behavior is ambiguous or the implementation change is not already authorized, report the disagreement and obtain the missing decision or authority before editing code. Do not make the documentation describe wished-for behavior, and do not silently turn a documentation pass into an implementation project.","type":"text"}]},{"type":"paragraph","content":[{"text":"4. Decide each affected doc's disposition before editing it.","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The document is…","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Do","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Still actionable; only specific facts drifted","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Update","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Built on a premise that no longer holds","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Archive / retire","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Do not patch a document whose premise is gone — you get something internally consistent and globally wrong, which is harder to spot than an obviously outdated file. A \"this section is superseded\" note left inline is not a third option. Maintainer bookkeeping does not belong in a reader's path; readers lack the context that makes it meaningful and only get confused. Move it out.","type":"text"}]},{"type":"paragraph","content":[{"text":"\"Archive\" means: out of the reader's path, still in history.","type":"text","marks":[{"type":"strong"}]},{"text":" Concretely: look for a convention the project already has (","type":"text"},{"text":"_archive/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"archive/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"deprecated/","type":"text","marks":[{"type":"code_inline"}]},{"text":", or whatever it uses) and follow it; if there is none, create ","type":"text"},{"text":"_archive/","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the same level as the file. Either way move it with ","type":"text"},{"text":"git mv","type":"text","marks":[{"type":"code_inline"}]},{"text":" so history follows, then repoint or remove every inbound reference. Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" delete it outright, and do not settle for adding ","type":"text"},{"text":"status: deprecated","type":"text","marks":[{"type":"code_inline"}]},{"text":" frontmatter while leaving the file where readers still find it — a retired document still in the reader's path is still being read.","type":"text"}]},{"type":"paragraph","content":[{"text":"Ask before archiving anything you did not create, for the same reason step 3 of Phase 4 needs agreement. ","type":"text"},{"text":"Running unattended and cannot ask: leave the document untouched and report it as needing retirement.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not patch it instead — a document whose premise died gets more misleading, not less, when you update its facts.","type":"text"}]},{"type":"paragraph","content":[{"text":"5. Find every copy of each changed fact — before you change it.","type":"text","marks":[{"type":"strong"}]},{"text":" This is the step that gets skipped, and it is where the classic failure lives: the obvious occurrence gets updated and three quiet ones do not. See ","type":"text"},{"text":"Verifying","type":"text","marks":[{"type":"em"}]},{"text":" below for the exact commands.","type":"text"}]},{"type":"paragraph","content":[{"text":"The highest-risk shape is ","type":"text"},{"text":"renumbering or inserting an item into a sequence","type":"text","marks":[{"type":"strong"}]},{"text":", because you are not changing one fact but a whole family of mutually-referencing ones: body text saying \"see step 7\", cross-references in sibling files, and — the nastiest — prose that baked the count into a sentence (\"the four checks below\"). That last one contains none of the numbers you are searching for, so a search by step number will never surface it.","type":"text"}]},{"type":"paragraph","content":[{"text":"There is no mechanical sweep for this, and you should not pretend otherwise.","type":"text","marks":[{"type":"strong"}]},{"text":" Two obvious scopings were measured and both fail:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search count words repo-wide","type":"text","marks":[{"type":"em"}]},{"text":" → 224,330 lines / ~550 MB on a real documentation repo (17.7 MB scoped to a single project directory). Nobody runs that, and an instruction that guarantees its own bypass is worse than no instruction.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search count words only in files that mention the subject","type":"text","marks":[{"type":"em"}]},{"text":" → bounded, but ","type":"text"},{"text":"wrong in the direction that matters","type":"text","marks":[{"type":"strong"}]},{"text":". Prose that bakes a count into a sentence is exactly the prose that refers to the subject by alias, translation, pronoun, or bare link — \"the four checks below\", 「预检有四个检查」 — and never by its title. Measured: a file containing a genuine stale count matched ","type":"text"},{"text":"zero","type":"text","marks":[{"type":"em"}]},{"text":" searches for the subject's name or filename. The filter is anti-correlated with the target.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"So do this instead, and report what it does not cover:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read the file you renumbered, in full.","type":"text","marks":[{"type":"strong"}]},{"text":" Most stale self-references live in it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build the file list, then search count words inside it.","type":"text","marks":[{"type":"strong"}]},{"text":" Nothing earlier in Mode 1 produced this list — do not reach for the inbound-reference search in ","type":"text"},{"text":"Updating references","type":"text","marks":[{"type":"em"}]},{"text":", which belongs to Mode 2 and answers a different question (\"what pointed at this ","type":"text"},{"text":"file","type":"text","marks":[{"type":"strong"}]},{"text":"\", not \"what discusses this ","type":"text"},{"text":"subject","type":"text","marks":[{"type":"strong"}]},{"text":"\"). Produce it here:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || { echo \"not in a git repo — pass the docs root explicitly\" >&2; exit 1; }\nrg -l -F \"\u003cthe subject's name>\" \"$ROOT\" --no-ignore --hidden -g '!.git'","type":"text"}]},{"type":"paragraph","content":[{"text":"That gives you files naming the subject outright; step 3 covers the ones that do not. It is a small set, so name the files directly rather than piping a list into ","type":"text"},{"text":"xargs","type":"text","marks":[{"type":"code_inline"}]},{"text":" (an empty list makes GNU ","type":"text"},{"text":"xargs","type":"text","marks":[{"type":"code_inline"}]},{"text":" run the search with no path at all, which searches the current directory instead — a wrong scope that looks like output):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"rg -n -i -H \\\n -e '\\b(one|two|three|four|five|six|seven|eight|nine|ten|both) [a-z]+\\b' \\\n -e '[一二三四五六七八九十两](个|条|步|项|点)' -e '[0-9]+(个|条|步|项|点)' \\\n -e '\\b[0-9]+ [a-z]+\\b' \\\n path/to/one.md path/to/two.md","type":"text"}]},{"type":"paragraph","content":[{"text":"Two details, both measured: ","type":"text"},{"text":"-H","type":"text","marks":[{"type":"code_inline"}]},{"text":" because ","type":"text"},{"text":"rg","type":"text","marks":[{"type":"code_inline"}]},{"text":" omits the filename when given exactly one file, and \"which file\" is the entire answer here. And the pattern deliberately takes ","type":"text"},{"text":"any","type":"text","marks":[{"type":"em"}]},{"text":" following word rather than a list of nouns — a list will not contain the noun your project uses (\"four ","type":"text"},{"text":"gates","type":"text","marks":[{"type":"strong"}]},{"text":"\", \"three ","type":"text"},{"text":"lanes","type":"text","marks":[{"type":"strong"}]},{"text":"\") and the miss is silent. Over a handful of files the extra noise is cheap; the missed line is not.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"List the subject's aliases yourself and search those","type":"text","marks":[{"type":"strong"}]},{"text":", then the count words in whatever that turns up. This is the step no tool does for you.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Then say what you checked: ","type":"text"},{"text":"\"read the renumbered file; searched count words in the N files that reference it by name; prose referring to it by other names was not mechanically covered.\"","type":"text","marks":[{"type":"em"}]},{"text":" That sentence is worth more than a green check mark that quietly meant one of the two failures above.","type":"text"}]},{"type":"paragraph","content":[{"text":"6. Clean derived values you meet along the way — but only in files you were already editing.","type":"text","marks":[{"type":"strong"}]},{"text":" Removing a stale count in a file you have open is hygiene, not scope creep. Opening unrelated files to hunt for more is scope creep. That boundary is what keeps this a reviewable change.","type":"text"}]},{"type":"paragraph","content":[{"text":"7. Report what you did","type":"text","marks":[{"type":"strong"}]},{"text":" in the structure under ","type":"text"},{"text":"What to report","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mode 2 — Consolidation","type":"text"}]},{"type":"paragraph","content":[{"text":"Consolidate redundant documentation while preserving all valuable content. The ","type":"text"},{"text":"Core principle","type":"text","marks":[{"type":"em"}]},{"text":" above governs every deletion in this mode.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 1: Discovery","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify all documentation files covering the topic","type":"text","marks":[{"type":"strong"}]},{"text":", and state the boundary you searched within (a directory, a suite, one project) before you search — the same bounded-scope rule Mode 1 step 1 uses. Two agents given \"the docs\" and no boundary consolidate different file sets. A topic-keyword sweep inside that boundary is the usual method — note ","type":"text"},{"text":"-F","type":"text","marks":[{"type":"code_inline"}]},{"text":", since topic terms like ","type":"text"},{"text":"C++","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".NET","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"v1.0.0","type":"text","marks":[{"type":"code_inline"}]},{"text":" are literals and as patterns they match almost everything: ","type":"text"},{"text":"rg -l -i -F -e '\u003ctopic term>' -e '\u003csynonym>' \u003cboundary> --no-ignore --hidden -g '!.git'","type":"text","marks":[{"type":"code_inline"}]},{"text":" This list scopes the entire consolidation, so a garbage list means a garbage analysis.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Count total lines across files","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"wc -l","type":"text","marks":[{"type":"code_inline"}]},{"text":" over the list from step 1","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Map content overlap","type":"text","marks":[{"type":"strong"}]},{"text":": for each heading in each file, note which other files cover the same ground. The artifact is a table of heading → files-that-also-cover-it; sections appearing in more than one file are the consolidation candidates. This step decides ","type":"text"},{"text":"overlap only","type":"text","marks":[{"type":"strong"}]},{"text":" — it does not decide keep-or-delete. A unique section can still be dropped in Phase 2 for a reason that has nothing to do with duplication (self-evident, superseded, a byproduct), so read this as ","type":"text"},{"text":"\"nothing here licenses deleting a unique section as redundant\"","type":"text","marks":[{"type":"em"}]},{"text":", not as ","type":"text"},{"text":"\"unique means it survives\"","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 2: Value analysis","type":"text"}]},{"type":"paragraph","content":[{"text":"For each document, build a section-by-section table:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Section","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Lines","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Value","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Reason","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"API Reference","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"25","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keep","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Unique endpoint documentation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Setup Steps","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"40","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Condense","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verbose but essential","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Env Var Table","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"30","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Delete","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Duplicates the table in ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", which is authoritative","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"The Delete example names an authoritative duplicate. Historical claims receive the same ordered Drift Test; a historical event and the current configuration are not necessarily the same fact.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep","type":"text","marks":[{"type":"strong"}]},{"text":" — unique, essential, frequently referenced","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Condense","type":"text","marks":[{"type":"strong"}]},{"text":" — valuable but verbose","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete","type":"text","marks":[{"type":"strong"}]},{"text":" — duplicate, one-time, self-evident, outdated","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Archive","type":"text","marks":[{"type":"strong"}]},{"text":" — a whole document whose ","type":"text"},{"text":"premise","type":"text","marks":[{"type":"em"}]},{"text":" is dead (a cancelled system's design notes, a retired service's postmortem). It is not stale current-state to be corrected and not duplicate content to be dropped. Without this category, \"superseded\" and \"it is a record\" pull the same document in opposite directions and whichever you read last wins.","type":"text"}]},{"type":"paragraph","content":[{"text":"A premise-dead ","type":"text"},{"text":"section","type":"text","marks":[{"type":"strong"}]},{"text":" inside a live document is the same problem one level down, and Archive does not accept it — it is defined over whole documents. Treat it as a Delete whose reason is the dead premise, and name it in the Phase 3 plan rather than deciding it yourself: \"the Kafka migration section, for a migration that was cancelled\" is exactly the kind of call the owner may answer with \"actually we still reference that\".","type":"text"}]},{"type":"paragraph","content":[{"text":"An Archive verdict removes that document from this consolidation.","type":"text","marks":[{"type":"strong"}]},{"text":" It does not go on to Phase 3 or Phase 4 — there is nothing to merge and nothing to condense. Handle it with Mode 1's archive procedure — the paragraph under ","type":"text"},{"text":"Mode 1 — Post-change governance","type":"text","marks":[{"type":"strong"}]},{"text":" that begins ","type":"text"},{"text":"\"Archive\" means: out of the reader's path, still in history","type":"text","marks":[{"type":"code_inline"}]},{"text":" — say in your report that you did, and carry on consolidating the rest. Do not put it in the Phase 3 line-count plan either: it is leaving intact, so counting its lines as \"reduction\" would claim a saving you did not make.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Run the Drift Test over every row as you go, and let it override the categories in ","type":"text"},{"text":"both","type":"text","marks":[{"type":"strong"}]},{"text":" directions:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A section that only restates values computable from elsewhere is a ","type":"text"},{"text":"Delete","type":"text","marks":[{"type":"strong"}]},{"text":" regardless of how well written it is (question 1).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Historical sections still receive questions 1 and 2 per claim. Their locally derivable aggregates and copied restatements can be removed; independent atomic observations may remain under question 3. Name any proposed removal of a unique historical atom in the value analysis and respect existing authorization; age or \"one-time record\" alone is not a deletion reason.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Detailed criteria: ","type":"text"},{"text":"references/value_analysis_template.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 3: Consolidation plan","type":"text"}]},{"type":"paragraph","content":[{"text":"Propose the target structure with real numbers, and present it for agreement — this is the plan Phase 4 asks you to get signed off before anything is deleted:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Before: 726 lines (3 files, high redundancy)\nAfter: ~100 lines (1 file + a pointer from the project's main doc)\nValue preserved: pending — established by the preservation check after execution","type":"text"}]},{"type":"paragraph","content":[{"text":"The before/after line measurements describe the proposed structure. ","type":"text"},{"text":"\"Value preserved\" is not","type":"text","marks":[{"type":"strong"}]},{"text":": at plan time it would be the deleting party asserting its own deletion was harmless, which is the self-certifying shape this skill exists to remove.","type":"text"}]},{"type":"paragraph","content":[{"text":"It is filled in after Phase 4 step 7, and it is ","type":"text"},{"text":"not a percentage","type":"text","marks":[{"type":"strong"}]},{"text":" — a percentage of what would have to be invented. It is a count against a stated denominator: ","type":"text"},{"text":"\"all 34 items on the step-1 inventory survived\"","type":"text","marks":[{"type":"em"}]},{"text":", or ","type":"text"},{"text":"\"31 of 34\"","type":"text","marks":[{"type":"em"}]},{"text":" naming the missing items and where each went.","type":"text"}]},{"type":"paragraph","content":[{"text":"The denominator is the Keep and Condense items only.","type":"text","marks":[{"type":"strong"}]},{"text":" The step-1 inventory deliberately also covers Delete sections, and those items are ","type":"text"},{"text":"supposed","type":"text","marks":[{"type":"em"}]},{"text":" to be absent from the consolidated file — counting them here would make \"all survived\" unreachable by construction, and a target nobody can hit is one people stop aiming at. They are accounted for on their own line: ","type":"text"},{"text":"\"and 6 items from Delete sections, each named with where its copy survives or why it is going\"","type":"text","marks":[{"type":"em"}]},{"text":". Two numbers, two questions, neither one hiding in the other. Write the denominator, not just the verdict — ","type":"text"},{"text":"\"every item I checked survived\"","type":"text","marks":[{"type":"em"}]},{"text":" is true of one item as easily as thirty-four, so it reports your diligence rather than the document's fate. Anything short of all is a finding to report, never a number to round up, and never a reason to undo your own condensation so the report reads better.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 4: Execution","type":"text"}]},{"type":"paragraph","content":[{"text":"Deleting someone's documentation is irreversible from the reader's side even when git can undo it. Present the Phase 3 plan and get agreement before step 3.","type":"text","marks":[{"type":"strong"}]},{"text":" Phase 3 says \"propose\" for a reason; the Core Principle governs how carefully you analyze, not whether you are authorized. If you are running unattended and cannot ask, do steps 1–2, stop, and report what you would delete.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Extract the preservation evidence first — before you write a single line of the consolidated document.","type":"text","marks":[{"type":"strong"}]},{"text":" The order is what makes the check mean anything: a claim list written after the rewrite is a list of what you happened to carry over, so it always matches. Written before, it is a specification the rewrite has to satisfy.","type":"text"}]},{"type":"paragraph","content":[{"text":"Be honest about what enforces that: nothing in the finished artifact distinguishes a list written before from one derived after, so this is a convention, not a gate. Give it the only teeth available — ","type":"text"},{"text":"emit the list before you start step 2","type":"text","marks":[{"type":"strong"}]},{"text":", into the report or a scratch file. A list that exists in writing before the rewrite can be checked against it; one that appears afterwards cannot be told from a transcription of the result.","type":"text"}]},{"type":"paragraph","content":[{"text":"The unit is one entry per load-bearing item, not per section and not per category.","type":"text","marks":[{"type":"strong"}]},{"text":" How finely to cut is a judgment call and two careful agents will land on different counts — that is tolerable. What is not tolerable is which clauses go missing when someone cuts coarsely, so two of them get their own entry no matter how you are counting:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The consequence clause.","type":"text","marks":[{"type":"strong"}]},{"text":" \"Roll back before retrying\" is an instruction; \"retrying on a half-applied migration corrupts the ","type":"text"},{"text":"events","type":"text","marks":[{"type":"code_inline"}]},{"text":" table and there is nothing that repairs it automatically\" is the reason anyone obeys it. Coarse lists keep the instruction and drop the consequence, which is the half that makes it survive a skim.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The symptom → cause mapping.","type":"text","marks":[{"type":"strong"}]},{"text":" \"A 401 from the deploy step means the token lapsed, not that the account is wrong\" cannot be re-derived from \"the token expires every 90 days\". It is the troubleshooting content, and it is one line long, so it disappears first.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Those two are a floor, not the boundary of what matters.","type":"text","marks":[{"type":"strong"}]},{"text":" They are named because they are the clauses coarse lists drop most reliably — not because a clause outside them is safe. Three that fall through and are worth checking for by hand: ","type":"text"},{"text":"ordering constraints","type":"text","marks":[{"type":"strong"}]},{"text":" (\"apply the migration before restarting the workers\" — no consequence stated, so the first rule does not reach it), ","type":"text"},{"text":"scope qualifiers","type":"text","marks":[{"type":"strong"}]},{"text":" (\"this applies to the ","type":"text"},{"text":"staging","type":"text","marks":[{"type":"code_inline"}]},{"text":" cluster only\"), and ","type":"text"},{"text":"thresholds buried in prose","type":"text","marks":[{"type":"strong"}]},{"text":" (\"backs off up to 5 attempts\"). Each is one clause long, each changes what the reader does, and none announces itself.","type":"text"}]},{"type":"paragraph","content":[{"text":"Go through ","type":"text"},{"text":"every","type":"text","marks":[{"type":"strong"}]},{"text":" section — including the ones marked Delete — and write down, from the source:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep → one distinctive verbatim line per item in it (each gotcha, each constraint, each snippet — a section holding three gotchas owes three lines, not one)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Condense → each load-bearing claim: every constraint, number, condition, warning","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete-as-duplicate → the items in it, and for each, where the surviving copy is.","type":"text","marks":[{"type":"strong"}]},{"text":" This is the step most likely to be skipped and the one that catches the worst failure: Phase 1 maps overlap ","type":"text"},{"text":"by heading","type":"text","marks":[{"type":"strong"}]},{"text":", so a section can be marked duplicate on its title while holding one gotcha no other file has. Skip the inventory and that gotcha is invisible to every later check — it was never on the list, so step 7 reports \"every item survived\" and means it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete for any other reason → the items in it and why each one is going. A deletion you can name is a decision; one you cannot is an accident you have not noticed yet.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All of the above → every URL, verbatim","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"What this list can and cannot do.","type":"text","marks":[{"type":"strong"}]},{"text":" It catches ","type":"text"},{"text":"recall","type":"text","marks":[{"type":"em"}]},{"text":" failures — you meant to carry something over and did not. It cannot catch ","type":"text"},{"text":"judgment","type":"text","marks":[{"type":"em"}]},{"text":" failures: if you decided at Phase 2 that something did not matter, it never enters the list, and step 7 will happily pass without it. ","type":"text"},{"text":"That gap is real and nothing in this procedure closes it.","type":"text","marks":[{"type":"strong"}]},{"text":" The Phase 3 plan goes to a human, but it carries target structure and line counts — not this list — so it cannot catch a misjudged item either; it is a check on the shape of the result, not on what went into it. Do not report step 7 passing as evidence that nothing valuable was lost — report it as what it is, a check that everything you ","type":"text"},{"text":"identified","type":"text","marks":[{"type":"em"}]},{"text":" was carried over. If you want the judgment reviewed too, the only thing that does it is showing the item list to someone who did not write it.","type":"text"}]},{"type":"paragraph","content":[{"text":"One sanity check before continuing: does the item count look like the source material? A three-page runbook that yields four items means you skimmed it — and a thin list is exactly the list that will later pass.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create the consolidated document, carrying every item on that list","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete the redundant source files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update every reference to them (","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" / the project's main doc, README, imports)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Leave a pointer to the new location","type":"text","marks":[{"type":"strong"}]},{"text":" in the main doc or README — create one if none existed. Consolidation moves content to a place nobody has a path to yet; without this step the work is discoverable only by whoever did it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify no broken links (see ","type":"text"},{"text":"Updating references","type":"text","marks":[{"type":"em"}]},{"text":" below — grepping the bare filename is not enough)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Before calling it finished, run the preservation check below","type":"text","marks":[{"type":"strong"}]},{"text":", using the list from step 1. It is a gate on this phase, not an optional appendix.","type":"text"}]},{"type":"paragraph","content":[{"text":"If you skipped step 1 and the sources were tracked in git, they are still recoverable — but mind which ref: ","type":"text"},{"text":"before the deletion is committed","type":"text","marks":[{"type":"strong"}]},{"text":" the content is at ","type":"text"},{"text":"git show HEAD:\u003cpath>","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"once it is committed","type":"text","marks":[{"type":"strong"}]},{"text":" that path no longer exists in HEAD and you need ","type":"text"},{"text":"git show HEAD~1:\u003cpath>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or the commit before the deletion). The path is repo-root-relative, so from a subdirectory use ","type":"text"},{"text":"git show HEAD:./\u003cpath>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Both wrong forms fail loudly with ","type":"text"},{"text":"fatal: path ... does not exist","type":"text","marks":[{"type":"code_inline"}]},{"text":", so you will know. What you must never do is take the expected strings from the consolidated file — that measures it against itself.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Verifying","type":"text"}]},{"type":"paragraph","content":[{"text":"Make documentation checks match ","type":"text"},{"text":"literally","type":"text","marks":[{"type":"strong"}]},{"text":" (facts contain characters a regex engine reads as wildcards — searched as a pattern, ","type":"text"},{"text":"v1.0.0","type":"text","marks":[{"type":"code_inline"}]},{"text":" also matches ","type":"text"},{"text":"v1X0X0","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"[2026-08-13]","type":"text","marks":[{"type":"code_inline"}]},{"text":" aborts as an invalid character range) and ","type":"text"},{"text":"contiguously","type":"text","marks":[{"type":"strong"}]},{"text":" (a fact spanning two lines is one fact, not two).","type":"text"}]},{"type":"paragraph","content":[{"text":"ripgrep","type":"text","marks":[{"type":"code_inline"}]},{"text":" gives you both: ","type":"text"},{"text":"-F","type":"text","marks":[{"type":"code_inline"}]},{"text":" matches literally, ","type":"text"},{"text":"-U","type":"text","marks":[{"type":"code_inline"}]},{"text":" lets a match span lines.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before delivering a literal command example, run the exact safe snippet as written in its declared shell and environment against an isolated fixture. Compare its accepted flags, flag precedence, result, and exit status with the implementation or CLI contract. Do not execute destructive, external-send, production-mutating, or credential-bearing examples against a live target; verify their flags and precedence from code or help output and state which end-to-end behavior was not exercised.","type":"text"}]},{"type":"paragraph","content":[{"text":"Always pass an explicit path.","type":"text","marks":[{"type":"strong"}]},{"text":" This is not a style preference: with no path argument and a non-interactive stdin — which is what an agent's shell has — ","type":"text"},{"text":"rg","type":"text","marks":[{"type":"code_inline"}]},{"text":" searches ","type":"text"},{"text":"stdin","type":"text","marks":[{"type":"em"}]},{"text":" instead of your files. Which of two symptoms you get depends on that stdin, and both are measured:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"stdin is closed or an exhausted pipe","type":"text","marks":[{"type":"strong"}]},{"text":" → exit 1, no output. Byte-identical to \"the string does not appear anywhere\", so the mistake reads as a clean pass. In a directory where four files contained the string, the pathless form reported nothing.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"stdin is inherited and never reaches EOF","type":"text","marks":[{"type":"strong"}]},{"text":" → the command ","type":"text"},{"text":"hangs","type":"text","marks":[{"type":"strong"}]},{"text":" until something kills it. If a search inexplicably hangs, check for a missing path argument before concluding the filesystem is slow.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Two flags belong on ","type":"text"},{"text":"every search that walks a directory","type":"text","marks":[{"type":"strong"}]},{"text":", for the reason spelled out under ","type":"text"},{"text":"What makes this check honest","type":"text","marks":[{"type":"em"}]},{"text":": ","type":"text"},{"text":"rg","type":"text","marks":[{"type":"code_inline"}]},{"text":" skips VCS-ignored files ","type":"text"},{"text":"and","type":"text","marks":[{"type":"em"}]},{"text":" hidden ones by default, and ","type":"text"},{"text":".github/","type":"text","marks":[{"type":"code_inline"}]},{"text":" — full of documented commands — is hidden. A search without them is looking at a strict subset of the docs (measured: 4 files instead of 6). Searches that name their files explicitly do not need them — ","type":"text"},{"text":"rg","type":"text","marks":[{"type":"code_inline"}]},{"text":" reads a path you hand it regardless of ignore or hidden rules — which is why the per-item checks later in this file omit them.","type":"text"}]},{"type":"paragraph","content":[{"text":"Set the search root once, and make it fail loudly rather than quietly shrinking:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || { echo \"not in a git repo — set ROOT to the docs root by hand\" >&2; exit 1; }","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not write ","type":"text"},{"text":"|| echo .","type":"text","marks":[{"type":"code_inline"}]},{"text":" here. A silent fallback to ","type":"text"},{"text":".","type":"text","marks":[{"type":"code_inline"}]},{"text":" scopes the search to whatever directory you happen to be in and still exits 0 — so \"repo-wide\" quietly becomes \"this subtree\", and a fact living one level up reports as absent (measured). If you are not in a repo, set ","type":"text"},{"text":"ROOT","type":"text","marks":[{"type":"code_inline"}]},{"text":" to the docs root by hand; the point is that you chose it.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Every copy of a fact, before you change it. Path and both flags are load-bearing.\nrg -U -F \"the exact fact string\" \"$ROOT\" --no-ignore --hidden -g '!.git'\n\n# Per-file counts — the artifact you paste into your report.\nrg -U -F --count-matches \"the exact fact string\" \"$ROOT\" --no-ignore --hidden -g '!.git'\n\n# Multi-line facts: the newline has to be a real newline. In bash/zsh that means

Docs Cleaner Documentation goes wrong in recurring ways, and they need different work. It rots. Something changed — a port, a path, a procedure, a decision — and the docs still describe the old world. The field's name for this is documentation rot or version drift : artifacts fall out of sync one at a time until people stop trusting the set. It sprawls. The same topic accumulates three files, each partly right, none authoritative. They trace to one root cause: a fact was written down in more places than it was defined. Everything below follows from fixing that. Core principle (governs both mo…

...';\n# \"\\n\" inside double quotes is a literal backslash-n and matches nothing (measured).\nrg -U -F

Docs Cleaner Documentation goes wrong in recurring ways, and they need different work. It rots. Something changed — a port, a path, a procedure, a decision — and the docs still describe the old world. The field's name for this is documentation rot or version drift : artifacts fall out of sync one at a time until people stop trusting the set. It sprawls. The same topic accumulates three files, each partly right, none authoritative. They trace to one root cause: a fact was written down in more places than it was defined. Everything below follows from fixing that. Core principle (governs both mo…

first line of the fact\\nsecond line of it' \"$ROOT\" --no-ignore --hidden -g '!.git'","type":"text"}]},{"type":"paragraph","content":[{"text":"-g '!.git'","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not optional once ","type":"text"},{"text":"--no-ignore","type":"text","marks":[{"type":"code_inline"}]},{"text":" is on: without it the search reports hits in ","type":"text"},{"text":".git/COMMIT_EDITMSG","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":".git/logs/HEAD","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the commit messages that ","type":"text"},{"text":"describe","type":"text","marks":[{"type":"em"}]},{"text":" your change — as surviving copies. Those can never be \"cleaned\", so a check that counts them trains you to wave off count mismatches, which disarms it for the real ones. ","type":"text"},{"text":"--no-ignore","type":"text","marks":[{"type":"code_inline"}]},{"text":" also restores ","type":"text"},{"text":"node_modules/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and other vendored trees; exclude those the same way when they appear.","type":"text"}]},{"type":"paragraph","content":[{"text":"Write down the expected counts before you search, not after.","type":"text","marks":[{"type":"strong"}]},{"text":" A count you decide once you have seen the output cannot fail. State which files should still contain the value and which should not, then run:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"rg -U -F --count-matches \"the old value\" \"$ROOT\" --no-ignore --hidden -g '!.git'\nrg -U -F --count-matches \"the new value\" \"$ROOT\" --no-ignore --hidden -g '!.git'","type":"text"}]},{"type":"paragraph","content":[{"text":"Compare each result against your list as ","type":"text"},{"text":"set equality","type":"text","marks":[{"type":"strong"}]},{"text":", in both directions: a file that appears and should not is a leftover, and a file on your list that does ","type":"text"},{"text":"not","type":"text","marks":[{"type":"em"}]},{"text":" appear is equally a failure — ","type":"text"},{"text":"--count-matches","type":"text","marks":[{"type":"code_inline"}]},{"text":" omits zero-match files from its output entirely, so a document that was supposed to receive the new value and silently did not looks exactly like a clean run.","type":"text"}]},{"type":"paragraph","content":[{"text":"What makes this check honest:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The old value does not always go to zero.","type":"text","marks":[{"type":"strong"}]},{"text":" A changelog entry, a decision log, or an \"as of \u003cdate> this was X\" sentence records history and legitimately keeps the old value (Drift Test question 3). Deleting those so a count reaches zero destroys an audit trail in order to satisfy a check. Name the historical files in advance; anything ","type":"text"},{"text":"outside","type":"text","marks":[{"type":"em"}]},{"text":" that list is a leftover.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--no-ignore --hidden","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is on purpose, and they are not the same flag.","type":"text","marks":[{"type":"strong"}]},{"text":" By default ","type":"text"},{"text":"rg","type":"text","marks":[{"type":"code_inline"}]},{"text":" skips both VCS-ignored files ","type":"text"},{"text":"and","type":"text","marks":[{"type":"em"}]},{"text":" hidden ones. ","type":"text"},{"text":"--no-ignore","type":"text","marks":[{"type":"code_inline"}]},{"text":" only restores the first group; without ","type":"text"},{"text":"--hidden","type":"text","marks":[{"type":"code_inline"}]},{"text":" the search still never opens ","type":"text"},{"text":".github/","type":"text","marks":[{"type":"code_inline"}]},{"text":", which is where contributing guides, issue templates, and workflows full of documented commands live (measured: adding ","type":"text"},{"text":"--hidden","type":"text","marks":[{"type":"code_inline"}]},{"text":" took a sample search from 4 files to 6). A convergence gate that cannot see those directories goes green over a surviving stale copy. Include them and judge the extra hits rather than assuming they do not matter.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Calibrate before you trust a zero — whichever tool you used.","type":"text","marks":[{"type":"strong"}]},{"text":" A search returning nothing has two causes: the fact is gone, or the command is wrong. They look identical. Before reporting \"no remaining copies\", run the same command shape against a string you ","type":"text"},{"text":"know","type":"text","marks":[{"type":"em"}]},{"text":" is present. If that also returns nothing, the instrument is broken, not the docs. This is the direct antidote to the pathless-","type":"text"},{"text":"rg","type":"text","marks":[{"type":"code_inline"}]},{"text":" failure above, and it costs one line.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Without ripgrep","type":"text"}]},{"type":"paragraph","content":[{"text":"git grep -nF \"fact\" -- .","type":"text","marks":[{"type":"code_inline"}]},{"text":" works in any git repo and is one implementation across platforms (unlike ","type":"text"},{"text":"grep","type":"text","marks":[{"type":"code_inline"}]},{"text":", whose recursion and symlink behavior differ between BSD, GNU, and drop-in replacements). It has these limits, all measured, all of which produce a confident wrong answer rather than an error:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"It searches tracked files only.","type":"text","marks":[{"type":"strong"}]},{"text":" The consolidated document you just wrote in Mode 2 is new and untracked — so a preservation check run through ","type":"text"},{"text":"git grep","type":"text","marks":[{"type":"code_inline"}]},{"text":" reports its content missing and you \"restore\" what was never lost. ","type":"text"},{"text":"git add","type":"text","marks":[{"type":"code_inline"}]},{"text":" it first, or read that file directly.","type":"text"}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"-F","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" with a multi-line string silently degrades to matching the lines independently.","type":"text","marks":[{"type":"strong"}]},{"text":" A file that kept only the first line of a two-line fact still reports a hit — so a lossy move gets certified as \"the content is still there\", the one error a preservation check exists to catch. True of both ","type":"text"},{"text":"grep","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"git grep","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"paragraph","content":[{"text":"With neither tool available, a contiguous check runs anywhere Python does:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 -c 'import sys, pathlib\n# .rstrip(\"\\n\") matters: your editor adds a trailing newline to needle.txt, and a fact\n# sitting at a file'\"'\"'s end has none — without the strip, that copy is silently missed.\nneedle = pathlib.Path(sys.argv[1]).read_text(encoding=\"utf-8\").rstrip(\"\\n\")\nfor f in sys.argv[2:]:\n n = pathlib.Path(f).read_text(encoding=\"utf-8\").count(needle)\n if n: print(f, n)' needle.txt doc1.md doc2.md","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Updating references to a file you moved or deleted","type":"text"}]},{"type":"paragraph","content":[{"text":"For a split entry or renamed section, the ","type":"text"},{"text":"delivery-entry replay","type":"text","marks":[{"type":"link","attrs":{"href":"references/delivery-entry-replay.md","title":null}}]},{"text":" supplies a bounded stale-anchor control and repaired-entry check. Read bare prose section references against the actual heading; link-checker success does not validate prose that it never parsed as a link.","type":"text"}]},{"type":"paragraph","content":[{"text":"Searching the bare filename finds some inbound links and misses the rest, then reports \"verified\". A file is referenced in more shapes than one:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"BASE=old-doc # filename without extension\nrg -n -F -e \"$BASE.md\" -e \"[[$BASE\" -e \"($BASE\" -e \"/$BASE\" \"$ROOT\" --no-ignore --hidden -g '!.git'","type":"text"}]},{"type":"paragraph","content":[{"text":"That covers Markdown links, wiki-style ","type":"text"},{"text":"[[old-doc]]","type":"text","marks":[{"type":"code_inline"}]},{"text":", bare paths, and imports. What it will not do for you:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Relative paths break when a file changes directory depth.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"../guide.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" from one level is ","type":"text"},{"text":"../../guide.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" from another. Grepping the filename finds the line; whether the path still resolves is a separate question, per link.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Verify no broken links\" has two directions, and Phase 4 only owes you one of them.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Inbound","type":"text","marks":[{"type":"em"}]},{"text":" — \"does anything still point at what I removed?\" — is what consolidation can break, and the search above answers it. Do that one; it is the step's actual obligation.","type":"text"}]},{"type":"paragraph","content":[{"text":"Outbound","type":"text","marks":[{"type":"em"}]},{"text":" — \"does every link in these files still resolve?\" — is a general docs-QA job, not something to hand-roll here. Use a real link checker:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"lychee --offline --root-dir \"$PWD\" docs/ # local paths only, no network\nlychee docs/ # also checks external URLs (slow, fails for unrelated reasons)","type":"text"}]},{"type":"paragraph","content":[{"text":"--root-dir","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not optional if the docs use root-relative links (","type":"text"},{"text":"/docs/x.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the normal style under mkdocs, Docusaurus, GitHub Pages): without it lychee reports every one of them as an error, which is the same false-flagging the paragraph below says to avoid. Anchors (","type":"text"},{"text":"x.md#section","type":"text","marks":[{"type":"code_inline"}]},{"text":") are not checked unless you add ","type":"text"},{"text":"--include-fragments","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"0 Total","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is not a pass — calibrate before you believe it.","type":"text","marks":[{"type":"strong"}]},{"text":" Measured (lychee 0.24.2): a path that does not exist fails loudly with exit 1, but a directory that exists and holds no Markdown prints ","type":"text"},{"text":"🔍 0 Total … ✅ 0 OK 🚫 0 Errors","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"exits 0","type":"text","marks":[{"type":"strong"}]},{"text":" — identical to a clean run. Point it one directory too high or too deep and you get a green check that looked at nothing. Read the ","type":"text"},{"text":"Total","type":"text","marks":[{"type":"code_inline"}]},{"text":" count: if it is 0, either confirm the files genuinely contain no links, or you searched the wrong place. (Files whose links are all in inline code or fenced blocks legitimately total 0 — lychee skips both, correctly.)","type":"text"}]},{"type":"paragraph","content":[{"text":"lychee","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"brew install lychee","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"cargo install lychee","type":"text","marks":[{"type":"code_inline"}]},{"text":") handles Markdown link forms that a shell pipeline does not: angle-bracket links ","type":"text"},{"text":"[x](\u003cmy file.md>)","type":"text","marks":[{"type":"code_inline"}]},{"text":", titled links ","type":"text"},{"text":"[x](y.md \"Title\")","type":"text","marks":[{"type":"code_inline"}]},{"text":", nested parens, reference-style ","type":"text"},{"text":"[x][ref]","type":"text","marks":[{"type":"code_inline"}]},{"text":", and links inside fenced code blocks all break a regex-and-","type":"text"},{"text":"test -e","type":"text","marks":[{"type":"code_inline"}]},{"text":" approach, in both directions — silently missing real breakage and falsely flagging valid links. If no link checker is available, say the outbound check was not run rather than substituting a hand-rolled one.","type":"text"}]},{"type":"paragraph","content":[{"text":"A checker validates only the links and fragments it parses. Its heading, anchor and autolink rules may differ from the intended reader's host. For example, an emoji heading containing a variation selector (VS16), or a bare email beside punctuation, can produce a checker error even when the host's permalink or ","type":"text"},{"text":"mailto:","type":"text","marks":[{"type":"code_inline"}]},{"text":" target works. These are parser-compatibility examples, not a portable heading-slug algorithm.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before calling a reported link broken or changing it, inspect the ","type":"text"},{"text":"exact Markdown in the intended reader host","type":"text","marks":[{"type":"strong"}]},{"text":": follow the rendered heading/permalink or inspect the email's actual ","type":"text"},{"text":"mailto:","type":"text","marks":[{"type":"code_inline"}]},{"text":" target. Classify a confirmed missing or mismatched target as a real broken link; classify a working host target with a checker error as parser portability. If that host cannot be checked, keep reader resolution unverified rather than inferring it from the checker. For a compatibility repair, preserve the visible label and contact identity, then verify both the checker result and the actual reader target. Do not remove a useful entry or change its intended destination merely to silence a diagnostic.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Preservation check (Mode 2)","type":"text"}]},{"type":"paragraph","content":[{"text":"The old form of this check was a list of things to tick off — \"essential procedures preserved\", \"gotchas preserved\". The person who deleted them ticks the boxes, so it can never fail. Replace self-assessment with evidence: name each specific item and show where it now lives. The categories further down are a checklist of ","type":"text"},{"text":"kinds","type":"text","marks":[{"type":"em"}]},{"text":" to sweep for, not the unit the evidence is counted in.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the list you built in Phase 4 step 1 — one entry per load-bearing item, written before the rewrite. (Missed that step? Phase 4 step 7 says how to recover the sources from git and which ref to use.) What you must never do is take the expected strings from the consolidated file: that only proves the file matches itself.","type":"text"}]},{"type":"paragraph","content":[{"text":"The method depends on the disposition, and using the wrong one produces a false deletion report.","type":"text","marks":[{"type":"strong"}]},{"text":" A section marked Keep should survive word for word; a section marked Condense was ","type":"text"},{"text":"supposed","type":"text","marks":[{"type":"em"}]},{"text":" to be rewritten, so a verbatim search for its old sentence correctly returns nothing — that is the condensation working, not content loss.","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Disposition","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"How to show it survived","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keep","type":"text","marks":[{"type":"strong"}]},{"text":", carried over as-is","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Per saved item: ","type":"text"},{"text":"rg -U -F \"\u003csaved distinctive line>\" \u003cconsolidated file>","type":"text","marks":[{"type":"code_inline"}]},{"text":" → a hit","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keep","type":"text","marks":[{"type":"strong"}]},{"text":", merged with another section — ","type":"text"},{"text":"only if the merge was recorded before the rewrite","type":"text","marks":[{"type":"strong"}]},{"text":" (in the Phase 3 plan or the step-1 inventory)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"A verbatim search will miss — merging two sections that state the same constraint in different words produces a third phrasing, and that is the point of Mode 2. Use the Condense method below. ","type":"text"},{"text":"Do not paste the original sentences back in to make the search go green","type":"text","marks":[{"type":"strong"}]},{"text":": that reinstates the duplication you were removing.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Which of those two rows applies is decided before the rewrite, never at check time.","type":"text","marks":[{"type":"strong"}]},{"text":" If you cannot point at a plan or inventory line saying this section was being merged, the row above applies and a miss is a miss. This is not bookkeeping: letting the agent whose search just failed pick which row it is graded by converts a hard verbatim gate into a soft one, and it converts it ","type":"text"},{"text":"only in the cases where it just caught something","type":"text","marks":[{"type":"em"}]},{"text":". The failure it lets through is not merging — it is a plain Keep section quietly reworded during the rewrite, its consequence clause dropped, relabelled \"merged\" so the softer method returns a hit on the weakened sentence. | ","type":"text"},{"text":"Condense","type":"text","marks":[{"type":"strong"}]},{"text":" | Per saved claim (each constraint, number, condition, warning): quote the line in the consolidated file that carries it. A claim you cannot point to was dropped, whatever the prose length says. | | ","type":"text"},{"text":"Delete","type":"text","marks":[{"type":"strong"}]},{"text":" | Per saved item: where the surviving copy is, or — if there is none — the reason it is going. \"It looked redundant\" is not a reason; naming what was in it is. |","type":"text"}]},{"type":"paragraph","content":[{"text":"The categories below are a ","type":"text"},{"text":"recall prompt, not the unit","type":"text","marks":[{"type":"strong"}]},{"text":" — they exist so you notice a class you forgot, and each one still resolves to per-item evidence from the table above. Ticked categories are not per-item evidence.","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Category (applies to Keep and Condense alike)","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Evidence to produce","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Essential procedures (setup, configuration)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"per the disposition row above","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Key constraints and gotchas","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"same, one per gotcha — these are the load-bearing claims a condensation most often drops","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Troubleshooting guidance","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"same","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Technical debt / roadmap items","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"same","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"External links and references","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"each URL saved from a ","type":"text"},{"text":"Keep or Condense","type":"text","marks":[{"type":"strong"}]},{"text":" section appears verbatim in the new file (string presence, not an HTTP request). URLs survive condensation intact or they were dropped — there is no \"shorter URL\". URLs saved from a Delete section follow the Delete row instead: say where the link survives, or that it is going and why. ","type":"text"},{"text":"Do not paste one back into the consolidated file to make this line green","type":"text","marks":[{"type":"strong"}]},{"text":" — that reinstates content you decided to drop","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Debug tips and code snippets","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"same; code is verbatim even inside a condensed section","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"A hit proves the string is in the file; it does not prove it is in the right place.","type":"text","marks":[{"type":"strong"}]},{"text":" A staging-only warning that landed under a \"Production\" heading, or a constraint moved out from under the conditional that scoped it, passes this check while now saying something false. When an item's meaning depends on where it sits, read the surrounding lines rather than stopping at the match — the same reason a lossy multi-line move can be certified as \"still there\".","type":"text"}]},{"type":"paragraph","content":[{"text":"Anything you cannot produce a hit for was not preserved — it was deleted. That may be the right call, but it belongs in the report as a deletion, not inside a checkmark.","type":"text"}]},{"type":"paragraph","content":[{"text":"A zero-deletion outcome is a legitimate result.","type":"text","marks":[{"type":"strong"}]},{"text":" If the value analysis says every section earns its place, report \"nothing to consolidate\" and stop. Line reduction is never a target — an agent that deletes something in order to have a number to report has inverted the whole point.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"What to report","type":"text"}]},{"type":"paragraph","content":[{"text":"State each of these explicitly. Silence on any of them reads as \"nothing to say\", which is rarely true:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inconsistencies found","type":"text","marks":[{"type":"strong"}]},{"text":" — what disagreed with what","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Authoritative source used","type":"text","marks":[{"type":"strong"}]},{"text":" — which file you treated as defining each fact, and on which ground you picked it when more than one looked declarative","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Files changed and why","type":"text","marks":[{"type":"strong"}]},{"text":" — one line each","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Derived values and redundant references removed","type":"text","marks":[{"type":"strong"}]},{"text":" — where each one was, and why it qualified as derived rather than as a fact worth keeping","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search evidence","type":"text","marks":[{"type":"strong"}]},{"text":" — the commands you ran and their counts, so every claim above is checkable rather than asserted. This is the same artifact listed under ","type":"text"},{"text":"Output artifacts","type":"text","marks":[{"type":"em"}]},{"text":"; both lists mean one report, not two.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The corrected procedure","type":"text","marks":[{"type":"strong"}]},{"text":", end to end, if a procedure changed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What is still unresolved","type":"text","marks":[{"type":"strong"}]},{"text":" — untouched exceptions, known-stale areas out of scope, risks you could not close","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In Mode 2 this report also carries the value-analysis table and the before/after metrics.","type":"text"}]},{"type":"paragraph","content":[{"text":"Point 4 is the one that gets dropped, and it is the one that compounds: naming a removed derived value teaches the reader why it should not come back.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Anti-patterns","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pattern","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Problem","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Instead","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Blind deletion","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Loses information","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Section-by-section value analysis first","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keeping everything","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No reduction achieved","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Apply the value criteria strictly","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Multiple sources of truth","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Guaranteed future divergence","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"One authoritative location, others link","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Orphaned references","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Broken links","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Update every reference after moving content","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Persisting a derived value","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Goes stale silently; nothing flags it","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Drift Test question 1 — do not write it","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Linking a derived value","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Scaffolding that also goes stale, plus false confidence the two are aligned","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Same — the value should not exist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Patching a doc whose premise died","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Internally consistent, globally wrong","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Archive it (disposition, step 4)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Updating the obvious occurrence only","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Quiet copies survive and contradict it later","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Search before editing (step 5)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Documenting unimplemented wishes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Doc and reality diverge from day one","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Follow step 3: repair only established, already-authorized behavior; otherwise report the disagreement","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Unbounded \"while I'm here\" sweeps","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Unreviewable diff; real changes get lost in it","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Bounded cleanup (step 6)","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output artifacts","type":"text"}]},{"type":"paragraph","content":[{"text":"A successful pass produces:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The corrected documents","type":"text","marks":[{"type":"strong"}]},{"text":" — with a single authoritative location per fact","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Value analysis","type":"text","marks":[{"type":"strong"}]},{"text":" (Mode 2) — section-by-section justification","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Before/after metrics","type":"text","marks":[{"type":"strong"}]},{"text":" (Mode 2) — lines reduced, value preserved","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search evidence","type":"text","marks":[{"type":"strong"}]},{"text":" — the commands run and their counts, so the claims are checkable","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Updated references","type":"text","marks":[{"type":"strong"}]},{"text":" — a pointer to the new location exists in the main doc or README, and every pointer to moved content resolves","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Next Step","type":"text"}]},{"type":"paragraph","content":[{"text":"After the docs are consistent, the natural follow-ons:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Docs are now consistent — [N] files updated, [M] derived values removed.\n\nOptions:\nA) Convert the recurring parts into a project rule — if the same drift keeps\n recurring, the fix is a rule in the project's main doc, not another cleanup pass\nB) Render or publish the result — if these docs have a build/publish step\nC) Nothing further — the docs are the deliverable","type":"text"}]}]},"metadata":{"date":"2026-11-02","name":"docs-cleaner","author":"@skillopedia","source":{"stars":1511,"repo_name":"claude-code-skills","origin_url":"https://github.com/daymade/claude-code-skills/blob/HEAD/daymade-docs/docs-cleaner/SKILL.md","repo_owner":"daymade","body_sha256":"f55f6c581eebfad5285c0ddc9984e717c396d87bc9a7cd80b6f8c8d59ee99eb2","cluster_key":"f6ab873f621afd56058f679fe8a86bd06fe076c6d6236e5359afd36fca9a4512","clean_bundle":{"format":"clean-skill-bundle-v1","source":"daymade/claude-code-skills/daymade-docs/docs-cleaner/SKILL.md","text_bytes":9390,"source_commit":"0633c92cdf1192ebed0b550384ea2a56f0abd520","skills_sh_rank":12964,"attachment_count":2,"text_attachments":2,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"daymade-docs/docs-cleaner/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"documents-office","category_label":"Documents"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"documents-office","import_tag":"skills-sh-top20k-2026-11","description":"Consolidates redundant documentation while preserving all valuable content; keeps a doc set truthful after things change. Modes: (1) POST-CHANGE GOVERNANCE — when code, scripts, config, env vars, ports, paths, deployment, auth, tests, or a documented procedure changed; also \"which docs are now wrong\", \"check docs for inconsistencies\", \"过时的命令/路径\", \"文档同步\". Use it even when the user mentions only the change and never the docs — updating them is part of the change, not optional cleanup. (2) CONSOLIDATION — \"clean up docs\", \"documentation bloat\", \"reduce documentation sprawl\", \"consolidate documentation\", \"too many doc files\", \"merge redundant docs\", \"merge these docs\", \"文档太多/太乱\", multiple files covering the same topic, or documentation exceeding 500 lines across multiple files on similar topics. Finds stale copies of a fact changed in only one place, values that should never have been persisted (counts, totals, \"N items\", restated summaries), rival definitions that drift apart, and orphaned cross-references.","disable-model-invocation":true}},"renderedAt":1793671389317}

Docs Cleaner Documentation goes wrong in recurring ways, and they need different work. It rots. Something changed — a port, a path, a procedure, a decision — and the docs still describe the old world. The field's name for this is documentation rot or version drift : artifacts fall out of sync one at a time until people stop trusting the set. It sprawls. The same topic accumulates three files, each partly right, none authoritative. They trace to one root cause: a fact was written down in more places than it was defined. Everything below follows from fixing that. Core principle (governs both mo…