audit-claude-md

name

audit-claude-md

description

Audit all CLAUDE.md files in the current project for staleness and coverage gaps. For each existing file, scores freshness by checking git churn in its scoped directory since the file was last touched; flags content drift for stale ones; discovers directories that should have a CLAUDE.md but don't; reports a ranked findings list and offers to invoke /init per-file after approval. Global and project-agnostic. Trigger when the user says "audit CLAUDE.md", "audit-claude-md", "are my CLAUDE.md files up to date", "check if CLAUDE.md is stale", "CLAUDE.md health check", "review project docs", "are the project docs outdated", or "refresh CLAUDE.md". SKIP when the user only wants to create a new CLAUDE.md from scratch (use /init instead) or only wants to find where to add one (use /where-claude instead).

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:

Commits in scope since last touch	Signal
0 – 4	Likely fresh
5 – 14	Possibly stale — worth reviewing
15+	Likely stale — recommend /init

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.
2. Orphaned — directory largely gone; recommend deletion.
3. Missing — new directories that should have a CLAUDE.md. Recommend /init.
4. Possibly stale — moderate churn; recommend a manual review pass.
5. 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.