doc-sweep

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- ABOUTME: Reusable doc freshness sweep: parallel Haiku auditors find staleness, the main session fixes it. -->
<!-- ABOUTME: Built 2026-08-03 after a manual sweep found a materially false public privacy policy. -->

# Doc sweep

Find every claim in the repo's documentation that the code has outgrown, and fix it.

**Announce at start:** "Using doc-sweep to find and fix stale documentation."

## The shape, and why it is this shape

Auditors **read**, the main session **writes**. That split is deliberate:

- A cheap model is good at "this file says X, the code says Y" and bad at writing prose that matches a project's voice and rules.
- Parallel writers on overlapping files clobber each other. One writer never does.
- The main session holds the project's conventions. A subagent does not, and will quietly reformat a house style into a generic one.

Do not delegate the edits. Do not skip the auditors and grep for staleness yourself: the whole point is that reading every file in full is what finds the things grep cannot phrase.

---

## Step 1: Establish ground truth first

**Everything downstream depends on this, so do it before dispatching anything.** An auditor with a wrong fact sheet manufactures wrong findings and you will apply them.

Gather from the repo, not from memory or from the docs being audited:

```bash
git log --oneline | head -3          # HEAD, so findings can be dated
git status --short                    # note if the tree is dirty before you start
find . -name "*.test.*" -not -path "./node_modules/*" | wc -l
cat package.json                      # scripts, dependency versions
```

Then gather whatever this project's docs make claims about. Typically: model and provider ids, feature flags, limits and budgets, table and column names, gate or check counts, phase or milestone status, and any measured number.

**Recompute measurements from the raw artifact.** If a doc quotes an accuracy figure, a benchmark, or a cost, open the file the number came from and recompute it. A number that has been copied between three documents is a number nobody has checked. This is where the highest value findings come from.

Write it all to one file in the scratchpad, `facts.md`, structured as:

- **Repo state**: commit, tree cleanliness, counts.
- **Current configuration**: the values, with the file and line that defines each.
- **Recent reversals**: what changed, what it reversed, and the phrases that are now stale. Spell out the exact stale wording so an auditor can match on it. "Any doc saying X is stale, the truth is Y."
- **Known open issues**: things that are genuinely broken. Auditors must not report these as staleness, and docs must not paper over them.
- **House style**: the project's writing rules, so nothing gets flagged as a style bug.

Hand auditors the **path** to this file. Never paste it into each prompt.

---

## Step 2: Group every doc into disjoint sets

Enumerate every markdown file, excluding `node_modules`, `.git`, and build output. Include the ones people forget:

- agent and command definitions (`.claude/`, `.codex/`, `AGENTS.md`) — **these teach other agents wrong facts, so they are the highest leverage of all**
- public or user facing documents: privacy policies, terms, READMEs, landing copy
- setup and runbook docs, where a stale instruction wastes a person's afternoon
- decision logs and plans

Then group them so **no file appears in two groups**. Aim for roughly one agent per 400 to 600 lines of prose, and keep related files together so one auditor sees both sides of a contradiction. Twelve to fifteen agents is a normal size for a mature repo.

---

## Step 3: Dispatch the swarm

One agent per group, all in a single message so they run concurrently. Use a cheap model (`haiku`) and a read-only agent type.

Every prompt gets:

1. The path to `facts.md`, with "read this in full first"
2. Its file list, with "read every line of each"
3. What to look for, **specific to those files**
4. The rules below
5. The output format below

**The rules, in every prompt:**

- READ ONLY. Do not edit, write, or create any file.
- Verify before reporting. If a claim is about code, open the code. If it is about a path, `ls` it. Do not report a suspicion you did not verify.
- Do not report style opinions, typos, or preferences. Only factual staleness.

**The output format, in every prompt:**

```
path:line | CLAIM: <stale text, quoted, max 15 words> | TRUTH: <correct fact, max 20 words>
```

Most important first, capped at 20 to 25 findings. `path | CLEAN` if a file is clean. Nothing else in the response.

**Per group, tell the auditor what "stale" means for that kind of file.** This is what separates a useful sweep from a noisy one:

| Kind of file | What counts as stale |
|---|---|
| Current state docs, READMEs, status pages | Anything not true right now. Highest risk of all. |
| Decision logs | **Never rewrite a superseded record, it is the record.** Report only: a superseded decision with no pointer to what superseded it, a present tense description with no superseding record at all, or a cross reference to a decision that does not exist. |
| Research docs | Not stale merely for describing what was true when researched. Stale when the project has since acted against the recommendation, or when a prediction has since been measured. Never flag an external citation or quote. |
| Plans | A step whose described implementation is not what shipped, a success criterion claimed as met that was not, a checkbox that lies. |
| Setup and runbooks | Any command, env var or step that no longer works. Cross check env vars both ways: named but unread, and read but undocumented. |
| Agent and command definitions | Any referenced path, script or check that does not exist. Any embedded "ground truth" list, which rots invisibly and poisons every agent that reads it. |
| Public or user facing docs | Any claim about data handling, capability or cost that overstates or understates what the system does. **Understating is not the safe direction, it is the legally dangerous one.** |
| Vision or roadmap sections | Future work written in the present tense with nothing marking it unbuilt. |

---

## Step 4: Triage what comes back

**Auditors are wrong sometimes and confidently so.** Before applying a finding, check it. Two failure modes recur:

- **A historical sentence read as a present tense claim.** "I reported it done with 585 tests" is a true sentence about the past. Do not "fix" it.
- **A rounding difference reported as an error.** 0.5 and 0.46 are the same measurement. Normalise to the measured value, but do not treat it as a defect.

Then work the findings in this order, because the first two can be actively harmful while the rest are merely wrong:

1. **User facing or public documents.** A privacy policy that understates what a system does is the specific thing regulators act on.
2. **Agent and command definitions.** Every hour they stay stale, they teach the next agent the wrong thing.
3. Current state docs, then setup docs, then everything else.

---

From sarveshcore/claude-skills, MIT.

More from sarveshcore/claude-skills