Agent Context Audit

You are auditing the agent-facing context layer of this project: everything AI coding agents read about the codebase that is not the codebase itself. This context rots silently — the code moves on, the descriptions don't — and a wrong "fact" in an instruction file or memory misleads every future session of every agent that reads it. Humans skim stale docs with a raised eyebrow; agents act on them.

Core rule: the codebase is the authority; context files are claims about it. Every concrete claim (a path, a CLI form, a field name, a status) gets verified with ls/grep/git log before being kept. Never "fix" code to match a context file.

The false-OK hazard: a grep against a moved file returns nothing and reads as "no findings." When a verification grep returns empty, first confirm the target still exists before concluding the claim holds. Empty is not OK; empty is unverified.

Shell portability: quote every glob-bearing argument (--include='*.py', not --include=*.py) and prefer git ls-files/find over bare globs — in zsh, an unmatched bare glob aborts the whole command with an error that's easy to misread as an empty (false-OK) result. This applies to every command you write during this audit, not just the examples below.

Step 0: Locate the context layer

Different tools keep context in different places. Discover what this project actually has — check every convention, not just the tool running this audit:

# Instruction files (project root and nested)
ls CLAUDE.md AGENTS.md GEMINI.md CONVENTIONS.md .cursorrules .windsurfrules \
   .clinerules .github/copilot-instructions.md 2>/dev/null
ls .cursor/rules/ .windsurf/rules/ .github/instructions/ .junie/ 2>/dev/null
find . -maxdepth 3 -name 'CLAUDE.md' -o -maxdepth 3 -name 'AGENTS.md' 2>/dev/null | grep -v node_modules

# User-level instruction files that apply to this project
ls ~/.claude/CLAUDE.md ~/.codex/AGENTS.md 2>/dev/null

# Agent memory (Claude Code: the dir name encodes the project path with
# slashes as dashes — ~/src/foo/bar → "-Users-you-src-foo-bar". Match the
# FULL encoded cwd: a project nested inside another produces two
# plausible-looking prefixes, and grabbing the parent's memory is easy.)
# find, not a bare glob — an unmatched glob aborts the whole command in zsh
find ~/.claude/projects -maxdepth 2 -type d -name memory 2>/dev/null | head

# Skills / reusable prompts — search by MARKER, not by fixed path: skill
# sources often live inside the repo (src/skills/, packages/*/skills/) and
# are symlinked into the standard locations.
git ls-files | grep -iE '(^|/)skill\.md$'
ls .claude/skills/ .claude/agents/ 2>/dev/null
# Which user-level skills belong to THIS project? Resolve the symlinks:
ls -l ~/.claude/skills/ 2>/dev/null | grep -F "$(pwd)"

# Permission & tool configs
ls .claude/settings.json .claude/settings.local.json ~/.claude/settings.json \
   .mcp.json .cursor/mcp.json 2>/dev/null

# Decision records
ls docs/adr/ docs/decisions/ 2>/dev/null

Every file found is in scope — including files for tools you are not. Sections below that target something this project doesn't have are skipped without comment.

Step 1: Memory hygiene

Where the agent keeps per-project memory (files it wrote for itself):

• Session journals and dated notes accumulate; consolidate, then delete. Extract only what is durable and not already recorded in decision records or git history: milestone one-liners, operational gotchas still true, open threads, people/context facts. Merge into topic memories. Detail the repo already records does not belong in memory.
• Rewrite the memory index (MEMORY.md or equivalent): one line per memory, grouped by kind (user / working style / project state / reference).
• Memories that turn out to be wrong get fixed or deleted — never left standing "for context."

Step 2: Contradiction audit (context bodies vs. code)

First gather recent ground truth — renames, deletions, moved modules:

git log --oneline -50

Then check every concrete claim in every memory and instruction file against it. For scale, a read-only search subagent can do the sweep, but require for each finding: the stale claim quoted, current reality with file:line evidence, and a severity — WRONG (actively misleading — fix now), DATED (harmless history — annotate), OK. Verify WRONG findings yourself before editing; subagents over-claim.

Classic rot classes: deleted scripts still cited, renamed CLI invocations, retired config fields, dead tool names, conventions that were proposed but never shipped.

Step 3: Instruction-file sync — and cross-tool consistency

Verify every concrete claim in each instruction file found in Step 0: the project files, any workspace/parent file's paragraph about this project, and user-level entries that affect it. Typical checks:

<project-cli> --help        # does the documented CLI surface match?
ls <documented paths>       # do named modules/dirs still exist?

Structure claims (pipeline stages, module lists, "X is powered by Y") must match current architecture — no retired stages described in present tense.

Cross-tool consistency (multi-tool projects only). When several instruction files coexist (say CLAUDE.md + AGENTS.md + .cursor/rules/), they drift from each other: a convention updated in one and not the others means different agents follow different rules in the same repo. Diff them for contradictions — build commands, test invocations, style rules, "always/never" directives. The durable fix is a single source of truth: one canonical file (AGENTS.md is the emerging cross-tool convention) with the tool-specific files reduced to a pointer, an include, or a symlink to it. Flag any substantive rule that exists in only one tool's file — either it belongs to all agents (promote to canonical) or it's tool-specific (mark it so).

Step 4: Decision-record statuses

If the project keeps ADRs/decision records:

grep -l "Status.*Proposed" docs/adr/*.md 2>/dev/null

• Implemented-but-Proposed: if code verifiably implements the decision, flip to Accepted with a one-line evidence note — unless the owner explicitly deferred acceptance.
• Missing supersession markers: when record B deletes what record A prescribed, A gets "Superseded by B" and B gets "Supersedes A." Don't rewrite bodies — they're history; only the status header moves.
• Retired subsystems: records describing mechanisms that no longer exist get a dated retirement note.
• Regenerate any index from disk; never hand-maintain it.

Step 5: Skill & rules rot

For each skill, rules file, or reusable prompt (Claude skills, Cursor .mdc rules, Copilot instruction files, saved prompts): extract every file path, command, and grep target it references, and verify each one exists. A rule whose embedded greps point at moved files fails silently (the false-OK hazard again). Also check each file's background blurbs — pipeline descriptions, CLI forms — against Step 3 findings. Rules scoped by glob patterns (Cursor/Copilot applyTo/globs) get their patterns checked too: a rule scoped to a directory that no longer exists never fires.

Duplicate trees: when Step 0 found the same skill name in more than one place (in-repo source, installed copy, a second package), diff the copies. Divergent duplicates mean one tree is stale documentation being silently served to agents — name the canonical tree and flag the other for sync or deletion.

Step 6: Permission & tool-config hygiene

In each permission/config file the tools keep (agent settings, MCP configs):

• Convert stale command forms to current ones; delete entries naming dead scripts; collapse accumulated one-offs into curated general patterns (keep the capability, cut the noise).
• Scan for credential literals. A key pasted into a permission entry or MCP config is a leak: it needs rotation, not just deletion of the line. Rotation is an external, owner-level action — never something this audit performs itself. Record it as the top-priority action item with file:line; in the meantime don't reproduce the key's value anywhere in your output.
• Tracked vs. local: read-only, team-shareable entries belong in the tracked settings file; personal or mutating ones in the local/gitignored one.
• MCP configs: verify each declared server still resolves (the package exists, the command runs) — dead servers are silent capability loss.

Step 7: Graduation pass

The highest-value step. For each memory or instruction that encodes feedback or a working rule, ask: is this deterministic? If a grep, AST walk, lint rule, or test can enforce it, graduate it: add the check to CI (or the project's invariant script), and shrink the context entry to the rationale plus a pointer to the check. The check becomes the enforcement; the prose stops being load-bearing — and unlike an instruction file, CI binds every agent and every human, whichever tool they use.

Judgment-shaped rules (taste, tone, "prefer root causes over guards") stay as context — a check can't hold them.

Before recommending a new check, list existing ones and diff: the rule may already be half-enforced.

Step 8: Apply, verify, record

• Memory-side and user-level fixes apply directly (they're not in git).
• Repo-side fixes (instruction files, decision records, new checks): run the project's test suite and structural checks, then commit. A new check lands with its first passing run in the same commit.
• Record the run: leave a dated completion note wherever the project tracks maintenance cadence, so an audit cycle that stops running goes visibly stale. No existing convention? Default to a dated line in the memory index (or a project-state memory) — the next audit's Step 0 will find it there.

Bonus: the issue tracker is context too

Where docs, decision records, or memories cite issue numbers (#NNN), verify against live state (gh issue view NNN --json state,title). A doc leaning on an open issue that has closed — or a closed one that reopened — is WRONG/DATED like any other claim. And open issues the codebase shows resolved get flagged for closure: the tracker is documentation and drifts like any other.

Output

1. Counts: memories consolidated / deleted / fixed; index size before/after.
2. Table of WRONG/DATED findings with evidence and what was done.
3. Cross-tool contradictions found, and the canonical-file consolidation applied or proposed.
4. Decision-record status changes applied.
5. Skill/rules and permission issues found and fixed.
6. Graduation recommendations (context → check), each with the proposed check's shape.