Audit CLAUDE.md files (staleness + coverage check)

Project-agnostic, global skill. It audits every CLAUDE.md in the current repo — checking whether existing files have drifted from the codebase and whether any directories should have one but don't — then produces a ranked report and offers to invoke /init on each problem file after per-file approval.

It pairs with /init (which writes/rewrites a CLAUDE.md) and /where-claude (which scouts new placements). This skill is the health-check that keeps existing docs from rotting silently.

The staleness model

Scope boundary

Each CLAUDE.md "owns" its directory and all subdirectories that do not have their own CLAUDE.md. This scoped ownership is how git churn is attributed: a commit that only touches files under frontend/ does not make the root CLAUDE.md stale if frontend/ has its own file.

Git churn signal

For each CLAUDE.md, the freshness baseline is its last-commit timestamp (git log -1 --format=%aI -- <path>). Commits since then that touched files within the file's scope (excluding noise — see below) are the staleness count. Thresholds:

Also treat as likely stale if any of these changed since the CLAUDE.md was last touched: a manifest file (package.json, pyproject.toml, go.mod, Cargo.toml, etc.), a CI config, or a top-level config file — these signal structural change.

Noise filter

Exclude from the churn count: lock files (*.lock, package-lock.json, yarn.lock, Pipfile.lock), generated/vendored dirs (node_modules, dist, build, out, vendor, .venv, target, __pycache__, .next, coverage), and binary/asset files. Count only source and config changes.

Content drift check (only for stale candidates)

For files flagged as possibly/likely stale, read them and do a quick sanity check:

• Does the file reference files, directories, tools, or commands that no longer exist?
• Are there documented conventions that appear to contradict what the code now shows?
• Does the file omit obvious top-level changes (e.g. a new language/framework added)?

This check is semantic and approximate — flag anything suspicious for the user to decide, not for you to auto-correct.

Orphaned CLAUDE.md

If a CLAUDE.md's parent directory has been largely deleted or its subtree collapsed into another module, flag it as orphaned. These need deletion, not /init.

Missing CLAUDE.md (coverage gap)

Apply the /where-claude scoring heuristic to find directories that qualify for their own CLAUDE.md but don't have one. Only report clear candidates; bias to restraint (same as /where-claude).

Procedure

1. Orient

• Confirm the cwd is the repo root the user intends (ask if in a monorepo/submodule).
• Find all existing CLAUDE.md files:

find . -name CLAUDE.md -not -path '*/node_modules/*' -not -path '*/.git/*'

• If there are none at all, say so and suggest /init for the root, then stop.
• For a large or unfamiliar repo, delegate the directory sweep to the Explore agent

and score from its summary.

2. Build the scope map

• For each CLAUDE.md, determine its owned scope: its directory minus subdirectories

that have their own CLAUDE.md.

• Note parent–child relationships so churn is not double-counted.

3. Score staleness (git churn)

For each CLAUDE.md:

• Get the last-touch timestamp: git log -1 --format=%aI -- <path>
• Count commits in scope since then, noise-filtered:

git log --oneline --since="<timestamp>" -- <scope-dir> | wc -l (then manually exclude noise paths in the scope if needed)

• Check whether any manifest/CI/config file in scope changed since then.
• Assign: Likely fresh / Possibly stale / Likely stale / Orphaned.

4. Content drift check (stale candidates only)

• Read each file flagged as possibly/likely stale.
• Note references to missing paths, contradicted conventions, or obvious omissions.
• Keep notes short — one or two bullet points per file max.

5. Coverage gap scan (missing CLAUDE.md)

• Apply the /where-claude heuristic to identify directories that clearly qualify but

have no CLAUDE.md. Report only strong candidates.

6. Report

Present the findings in this order:

1. Likely stale — high churn, content drift confirmed or suspected. Recommend

/init to rewrite.

1. Orphaned — directory largely gone; recommend deletion.
2. Missing — new directories that should have a CLAUDE.md. Recommend /init.
3. Possibly stale — moderate churn; recommend a manual review pass.
4. Likely fresh — low churn; list briefly with last-touch date for completeness.

For each finding include: file path, last-touch date, churn count, and a one-line rationale. For content drift, add the specific concern(s).

7. Offer per-file action

For each file in categories 1–3:

• Offer to invoke /init (for stale/missing) or flag for manual deletion (orphaned).
• Get approval per file before acting — never batch-rewrite without confirmation.
• Do NOT auto-run /init without explicit per-file approval.

Guardrails

• Never modify or delete any CLAUDE.md without explicit per-file user approval.
• Scope churn attribution correctly: do not charge parent files for commits that only

touched a child-scoped subtree.

• Apply the noise filter consistently; lock files and generated dirs must not inflate

staleness scores.

• Content drift check is approximate — flag concerns, do not make authoritative

pronouncements about what the file "should" say.

• Coverage gap recommendations: bias to restraint; a few clear candidates beat a long

list of borderline ones.

• Never fabricate repo facts — base every finding on files and git history you actually

observed.

• For a large repo, delegate the directory sweep to the Explore agent rather than

reading every file in the main thread.