Doc Sweep

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:

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:

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.

Step 5: Sweep the code comments too

The auditors cover markdown. Do this part yourself, because nobody assigns it and it rots hardest:

# adapt the pattern to whatever this project's reversal was about
grep -rn "<the stale phrase>" lib/ app/ src/ --include="*.ts" --include="*.tsx" | grep -v ".test."

Look for doc comments justifying a decision by a constraint that no longer exists, and for user facing strings: error messages, empty states, toasts. A string shown to a person is a factual claim about the system and goes stale exactly like a document. In the sweep this skill was built from, the single worst finding was a chat error message telling the owner they had used up their "free model budget" months after the project started paying.

Also watch for a module that documentation says is wired in and the code no longer calls. Report it, do not delete it: dead code is the owner's call.

Step 6: Fix, verify, report

When rewriting a stale passage, say what changed and why, not just the new fact. A corrected document that hides its own history teaches nobody, and the reversal is usually the most useful thing on the page. Keep the old reasoning where it was instructive and mark it clearly.

Then:

# whatever this project uses
pnpm verify && pnpm gates

Run the tests even though you "only edited docs". A test may assert on a user facing string you corrected. If one fails, that is the suite working: fix the assertion and leave a comment saying the copy went stale, so the next person understands why the expectation moved.

Report to {{USER}}:

• The count of files swept and findings applied
• The two or three findings that actually mattered, not a list of every line touched
• Anything found that is a code issue rather than a doc issue, stated plainly and left unfixed unless he asks
• Anything an auditor claimed that you checked and rejected, with why

Do not commit. Commits need {{USER}}'s explicit green hand.