docs-cleaner
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.
1How It Works & Mechanism
This is a purely instruction-based skill (zero scripts): all mechanisms are defined in the body of SKILL.md. Its core value lies in a taxonomy of 'why documentation rots' and the corresponding remediation workflows, executed directly by the agent itself.
They trace to one root cause: **a fact was written down in more places than it was defined.** Everything below follows from fixing that.
The core discriminator is the three-question Drift Test (evaluated sequentially, halting on the first match): Can the value be computed from already recorded details? → derived, do not record; Can it not be computed, but an authoritative definition exists elsewhere? → copy, convert to link; Otherwise, is it a 'record of fact at a specific point in time'? → recordable, and must not be cleared as drift.
ask these three questions **in order, and stop at the first hit**: **1. Can this be computed from details already recorded here or in the authoritative source?**
Mode 1 (Post-Change Governance) executes in a strict 7-step sequence where the order itself forms the core argument: Enumerate affected facts from changes → Determine SSOT → Resolve drift between implementation and docs → Assign disposition (update or archive) for each doc → Search the entire repository for copies of each fact before modifying → Clean up derived values along the way → Report back following a fixed structure.
**2. Identify the authoritative source (SSOT) for each affected fact.** Which file *defines* this port / path / procedure — as opposed to mentioning it?
Deletion is transformed into a disciplined ritual: Archiving = moving out of the reader's path while preserving history (git mv to _archive/ and repointing all incoming links); status: deprecated tags left in-place are prohibited, and archiving documentation not owned by the user without explicit confirmation is banned.
"Archive" means: out of the reader's path, still in history. Concretely: look for a convention the project already has (`_archive/`, `archive/`, `deprecated/`, or whatever it uses) and follow it; if there is none, create `_archive/` at the same level as the file. Either way move it with `git mv` so history follows
Content-loss prevention gate for Mode 2 (Consolidation): Before rewriting, produce a granular 'load-bearing items list' (consequence clauses, symptom→cause mappings, sequencing constraints, scope qualifiers, and thresholds must be isolated), which becomes the specification for post-rewrite verification before deletion.
**The consequence clause.** "Roll back before retrying" is an instruction; "retrying on a half-applied migration corrupts the `events` table and there is nothing that repairs it automatically" is the reason anyone obeys it.
Verification commands contain extensive empirical pitfall logs: rg searches stdin when no path is provided; -F and -U are required for literal and multi-line matching; trade-offs between --no-ignore --hidden and -g '!.git'; git grep only inspects tracked files; lychee reporting '0 Total' does not constitute a pass.
`rg` skips VCS-ignored files *and* hidden ones by default, and `.github/` — 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).
Built-in functional boundaries: Hierarchical compression for single files that grow too large is delegated to claude-md-progressive-disclosurer (daymade-claude-code suite); this skill focuses exclusively on truthfulness and deduplication.
That is what daymade-claude-code's `claude-md-progressive-disclosurer` skill is built for; prefer it when the problem is size and layering rather than truth or duplication.
2Core Capabilities
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | ripgrep (rg) |
| cli | lychee（可选外链检查器，brew/cargo install） |
| cli | git（git grep / git mv / git show 归档与恢复） |
4Recommended Governance & Evidence
- scripts/: Local script or command execution: The skill contains no scripts; SKILL.md instructs the agent to execute read-only search tools (rg, git grep, lychee) and git mv/file rewrites in the host environment.
- 网络端点: External network access declaration: None by default; lychee will send requests to external URLs found in docs when run without --offline (the documentation notes 'also checks external URLs').
- 本地工作目录: File I/O and artifact output: Modifies, consolidates, or deletes document files according to the Phase 3 plan; archives files via git mv to _archive/; rewrites governance files such as CLAUDE.md/AGENTS.md under the same governance rules.
5Second-Pass Verification
- [ok] 纯指令无脚本（资产面） — glob 全量文件：SKILL.md + references/value_analysis_template.md，无 scripts/ 目录。
- [ok] Drift Test 三问与顺序规则 — 原文 'in order, and stop at the first hit' 与 Q1/Q2/Q3 全在；第 3 问优先级说明亦逐字存在。
- [ok] Mode 1 七步与 SSOT 判定 — 步骤编号 1-7 与 SSOT 'defines vs mentioning' 判据原文在。
- [ok] 归档纪律（git mv + 不就地 deprecated） — 'out of the reader's path, still in history'、'git mv'、'do **not** settle for adding status: deprecated frontmatter' 均命中。
- [ok] 删除需人门 / 无人值守停手 — 'Present the Phase 3 plan and get agreement before step 3' 与 'Running unattended and cannot ask: leave the document untouched and report it' 存在。
- [ok] preservation check 防 recall 不防 judgment 的自评缺口 — 'It catches *recall* failures ... It cannot catch *judgment* failures' 原文在，未见自我拔高。
- [ok] 搜索命令面防坑（rg/lychee） — pathless-rg/stdin 陷阱、-F -U、--no-ignore --hidden、lychee '0 Total' 各段均在，附 measured 数字。
- [ok] 网络面仅 lychee 外链可选检查 — 代码零命中；唯一网络点是 SKILL 对 lychee 非 --offline 模式的说明，且推荐先 --offline。
6Verdict & Scenarios
91fa2a6f6082c893…