docs-cleaner

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

AGENTS.md

Audit 0.4.1 · source sha ca718c340cc0 · 31 Oct 2026Report an issue or request a re-scan

• Publisherdaymade GitHub userOwner of the repository this skill is read from
• Source folderdaymade/claude-code-skills/daymade-docs/docs-cleanerThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictca718c340cc0A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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,…

---
name: docs-cleaner
disable-model-invocation: true
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.
---

# 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 modes)

**Critical evaluation before deletion. Never blindly delete.** Analyze each section's
unique value before proposing removal. The goal is reduction without information loss.

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.

## Which mode are you in?

| The user said / the situation | Mode |
|---|---|
| "I changed X" / a diff exists / a procedure was updated | **1 — Post-change governance** |
| "which docs are now wrong", "check for stale commands/paths" | **1 — Post-change governance** |
| "clean up the docs", "too many files on this", "merge these" | **2 — Consolidation** |
| A topic is spread over several files with no clear owner | **2 — Consolidation** |

They share the Drift Test below. When both apply, run Mode 1 first: consolidating docs
that are *also* factually stale just produces one confidently wrong document.

**A note on `CLAUDE.md` / `AGENTS.md`:** 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 *restructuring a single oversized one* — pushing low-frequency
detail down into references while keeping the top level lean. 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. If it is not
available, Mode 2 still handles the file — you just do the value analysis by hand.

---

## The Drift Test (the core of both modes)

Before writing any value into a document — and when deciding whether an existing one
earns its place — ask these questions **in order, and stop at the first hit**:

**1. Can this be computed from details already recorded here or in the authoritative
source?**
→ It is a **derived value**. 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.

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.

*Exception — generated navigation.* 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.

**2. Not computable, but the same fact is authoritatively defined somewhere else?**
→ It is a **copy**. Link to that definition. Do not restate the value.

**3. Neither derivable nor copied — it independently records what was true at a
particular moment?**
→ It may remain as an **atomic historical observation**: a dated change, original
measurement, price observation or decision. Never replace its past value with a
current value or a current-config link.

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.

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.

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 acti

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/daymade/claude-code-skills
git -C claude-code-skills checkout ca718c340cc0

Works in

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source ca718c340cc0

Questions about docs-cleaner

• github.com/daymade/claude-code-skills/tree/main/daymade-docs/doc — the audited source at commit ca718c340cc0 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology