claude-md-improverlisted

# CLAUDE.md Improver Instruction files rot in a way code does not: nothing compiles them, no test imports them, and every reference inside them is a plain string. A path can move, a skill can be extracted to a plugin, an agent can be added — and `CLAUDE.md` keeps confidently pointing at the old world. The cost lands on exactly the sessions least able to notice: fresh cloud checkouts, worktree agents, scheduled routines. This skill mechanically checks the claims instruction files make against what is actually on disk. **Output is a proposal, never a silent write.** Show findings, get a decision, then edit. ## Arguments - (none) — audit `CLAUDE.md`, `AGENTS.md`, and `.claude/rules/*.md`. - `--file <path>` — audit one file only. - `--apply` — after review, apply the accepted fixes. - `--dry-run` — report only; make no edits even if accepted. ## Scope note This is about **instruction quality**, not prose style. Do not rewrite wording that is merely verbose. Every finding must be a checkable claim that is false, or a documented surface that is missing. If you cannot state the finding as "X says Y, but Y is not true", it does not belong in the report. ## Process ### Step 0: Track the run Use TodoWrite: inventory → dangling paths → table drift → unresolvable mandates → undocumented surfaces → rank → propose → apply. ### Step 1: Dangling path references Every repo-relative path mentioned in an instruction file should exist. Extract and test them: ```bash # path-like toke