---
name: claude-md-audit
description: Audit CLAUDE.md and the memory store (MEMORY.md + fact files) for drift — stale path citations, cross-file contradictions, duplicated facts, and bloat. Use periodically (monthly, or after a big restructure), not on every change. Read-only by default; reports findings by severity with file:line + suggested fix, and routes anything not fixed this session to a follow-up note. Auto-activates on `/claude-md-audit`.
tools: [Bash, Read, Grep, Glob, Edit]
---

# CLAUDE.md + Memory Audit Skill

This repo restructures `courses/` often (subject-first renames, archive moves, supersessions). Every restructure risks leaving CLAUDE.md or a memory citing a path that no longer exists. This skill catches that drift on a **periodic** scan rather than trying to check every commit (the most-skipped kind of rule).

## Scope

The canonical instruction + memory surface:

- **`CLAUDE.md`** (repo root) — the single project instruction file.
- **`MEMORY.md`** — the memory index loaded each session (at `~/.claude/projects/C--GitHub-shidler/memory/MEMORY.md`).
- **The memory fact files** — `feedback_*.md`, `project_*.md`, etc. in the same dir.

## The four checks (run all, in order)

### 1. Stale references (highest value here)

Extract every path CLAUDE.md and MEMORY.md cite (backtick-quoted paths, links, table "Path" columns) and confirm each resolves in the live tree:

```bash
# pull backtick-quoted paths from CLAUDE.md, test each
grep -oE '`[^`]+`' CLAUDE.md | tr -d '`' | grep -E '/|\.md|\.json|\.xlsx|\.py' | sort -u \
  | while read p; do [ -e "$p" ] || echo "MISSING: $p"; done
```

Do the same for MEMORY.md and for any path a fact file names in its body. Flag each miss with the citing `file:line` and the likely correct path (grep the tree for the basename — a restructure usually *moved* it, didn't delete it).

### 2. Cross-file contradictions

Compare claims that appear in more than one place — CLAUDE.md vs. a memory, or two CLAUDE.md sections. Common drift: a stage count, a weight table, a "current vs. archived" status, a naming convention. Quote both sides with `file:line`. (Example class: CLAUDE.md's "Active Courses" table vs. a `project_*` memory's description of the same course.)

### 3. Duplication + bloat

Facts stated in full in two places should live in one home with a pointer from the other (single-sourcing). Flag: a fact duplicated between CLAUDE.md and a memory; a memory that just restates code/git history (which the memory rules say not to store); a CLAUDE.md section that has grown past its usefulness.

### 4. Structural hygiene

- **Broken index links** — a `MEMORY.md` line pointing at a memory file that doesn't exist (run `/memory-hygiene`'s validator if present, or grep the linked filenames).
- **Orphan memories** — a fact file not referenced in `MEMORY.md`.
- **Dangling `[[refs]]`** — a `[[name]]` in a memory body with no matching file (may be a deliberate forward-ref — flag, don't auto-fix).

## Output

You are **read-only by default** — report and *offer* fixes; don't rewrite without approval. Group findings by severity:

```
CLAUDE.md + memory audit — <date>

ERRORS (broken references / contradictions)
- CLAUDE.md:NN — cites `path/that/moved.md`; now at `new/path.md`. Fix: update the citation.

WARNINGS (duplication / bloat / orphans)
- MEMORY.md — `feedback_foo.md` orphaned (not indexed). Fix: add index line or rotate.

HYGIENE (minor)
- feedback_bar.md — dangling [[baz]] (likely forward-ref; leave unless typo).
```

End with one terminal line:
`CLAUDE.md audit: <N> stale refs / <N> contradictions / <N> dup-or-bloat / <N> hygiene. <recommendation>.`

Route anything you don't fix this session into a short follow-up note in the audit output so it isn't lost. Fold in `npm run docs:validate` or an equivalent link-checker if one exists in the repo.

## Why a ritual, not a per-change rule

Drift is better *prevented* by single-sourcing each fact (one home + pointers) and *caught* by this periodic scan. Run it monthly or right after a `courses/` restructure — not on every edit.