Jonathon's AI Wiki

CLAUDE.md Context Rot Cleanup — the doc-cleanup Skill (aka-luan)

7 min read

Source: raw/reddit-1us9hfz.md (r/ClaudeAI, u/eliaff, score 151 / 29 comments, posted 2026-07-10) — cites github.com/aka-luan/doc-cleanup, checked directly against the live repo on 2026-07-10 (MIT, 26 stars, single SKILL.md at skills/doc-cleanup/SKILL.md, matches the post’s description).

After three weeks building a product almost entirely with agents, a disciplined documenter asked Claude to evaluate what in the repo’s own required-reading docs was hurting its reasoning — expecting a clean bill of health. Instead Claude found the docs were 75% finished-work history masquerading as current instructions, plus several specific rot patterns that had been silently misleading every agent session. The author turned the audit into a repeatable Claude Skill rather than a one-off cleanup.

Key Takeaways

  • Over-documenting is not the same as documenting well. The author was disciplined the whole three weeks — milestones checked off, decisions logged, gotchas recorded — and still ended up with docs that actively degraded agent reasoning. Volume and currency are different axes.
  • The three required-reading docs totaled 1,085 lines; ~75% was finished work — fully-checked checklists, phase-completion logs, old verification notes. Every session paid the token cost to read history nobody needed anymore.
  • Agents trust these files more than they trust their own searches — by design. That’s what the files are for. But it means a doc doesn’t have to be wrong in an obvious way to cause damage; it only has to be slightly behind the code.
  • Five concrete rot patterns surfaced (see below) — each one a distinct failure mode, not just generic staleness.
  • The cleanup is now a repeatable skill, not a one-off: inventories the markdown files, verifies every claim against the actual code before flagging it, reports findings, and only rewrites after human approval. Nothing is deleted — history moves to docs/archive.
  • Result: 1,085 lines of required reading cut to 266 (about 75% reduction) while preserving the archived history.
  • Verified via direct repo check (2026-07-10): the public README describes the same mechanism in more formal terms — six specific rot patterns (completed-work logs, executed plans never rewritten, internal contradictions, stale facts diverging from code, dead file paths, authority drift) worked through five phases (inventory, diagnosis, reporting, execution, verification), with a mandatory approval gate before any change lands.^[inferred]

The Five Rot Patterns Found in the Original Post

  1. Pure finished-work history disguised as instructions. Fully-checked checklists and phase-completion logs sitting in the same file as active rules, with no separation between “what we did” and “what to do.”
  2. The same fact stated two contradictory ways in one file. The pricing doc listed enabled payment methods differently in two places — and one version referenced a line number that no longer existed.
  3. A table “corrected” by a footnote three paragraphs below it, but the table itself never edited. The author’s own framing: “Guess which one an agent reads.” Agents don’t reliably read past the first authoritative-looking statement.
  4. Stale status labels. Two features marked “awaiting merge/deploy” had actually been on main for days — the doc hadn’t been touched after the merge landed.
  5. A dead cross-repo path that silently failed every time. A hard rule in AGENTS.md pointed at a sibling repo via a Windows path (A:\Dev\...) — left over from before the author moved to WSL. No agent ever flagged the rule as broken; each one just silently failed to follow it.

How the Skill Verifies Before Flagging

The skill doesn’t just pattern-match for staleness — it checks claims against ground truth before surfacing them:

  • “Awaiting merge” claims are checked with git merge-base against the actual branch state, not taken on the doc’s word.
  • File-path references are checked with grep against the real filesystem, catching dead paths like the WSL-migration Windows path above.
  • Contradictions are surfaced for human review rather than auto-resolved — the skill reports, it doesn’t silently pick a winner.
  • Nothing is deleted. Finished-work history moves to docs/archive rather than disappearing, preserving the audit trail while clearing it out of the always-loaded read path.
  • A mandatory approval gate sits before any rewrite. The skill’s five-phase flow (inventory → diagnosis → reporting → execution → verification, per the repo’s own README) stops before the execution phase until a human signs off.^[inferred]

Relationship to First-Party Tooling

This is a community pattern filling a gap Anthropic is now also addressing natively. Claude Code’s /checkup command (announced by Boris Cherny, 2026-07-08) runs a similar one-pass audit — deduplicating CLAUDE.md, reorganizing a bloated root file into nested CLAUDE.md files plus skills, and cleaning up unused skills/MCP servers/plugins — with its own confirm-before-change gate. /doctor diagnostics cover an overlapping but narrower slice (proposing trims of content Claude could re-derive from the codebase). See the CLI Reference for the authoritative first-party detail on both. The doc-cleanup skill predates neither by much and is more narrowly scoped to the documentation-rot diagnosis specifically (the six named patterns above), whereas /checkup bundles doc cleanup into a broader maintenance sweep (skills, MCP servers, hooks, update, auto mode, pre-approvals) — worth running both rather than treating either as a full replacement for the other.^[inferred]

Try It

  1. Install the skill from github.com/aka-luan/doc-cleanup (MIT license, single SKILL.md) and point it at your project’s required-reading docs (CLAUDE.md, AGENTS.md, onboarding docs).
  2. Before running it for real, skim the six rot patterns above against your own docs — the table-vs-footnote and dead-cross-repo-path patterns are easy to miss by eye.
  3. Let the skill report before it rewrites — review the flagged items, especially any “awaiting merge” or file-path claims, before approving.
  4. Route history to docs/archive instead of deleting it, matching the skill’s default behavior.
  5. If you’re already on a build with /checkup (2026-07-08+), compare its output against doc-cleanup’s report on the same repo — they target overlapping but not identical problems.
  6. Re-run periodically, not just once — the same rot (stale status labels, contradicted facts) will reaccumulate as a project evolves.

Open Questions

  • No evidence of official Anthropic affiliation. This is a community-built skill (single author, aka-luan), not a first-party tool — treat it with the same scrutiny as any other community skill before installing.
  • Nested CLAUDE.md hierarchies untested here. The source describes a flat multi-doc setup (three required-reading files); unclear from the post whether the skill has specific handling for project/user/enterprise CLAUDE.md layering.
  • Not yet run against this vault’s own wiki/CLAUDE.md or karpathy/CLAUDE.md. A natural dogfooding candidate, unexplored as of this ingest.

Graph View

Backlinks