| name | context-guidance-audit |
| description | Multi-phase, subagent-driven deep audit and remediation of codebase guidance (root agent instructions, docs, module context files, skills/agents references, task routing). Phase 1 subagents write verified findings only; Phase 2 subagents verify and fix guidance. Use when the user asks to audit, refresh, or fix agent context, CLAUDE.md or AGENTS.md drift, stale docs, contradictory rules, or run a context-guidance deep dive. |
Context Guidance Audit
Orchestrate a two-phase, multi-subagent pass over everything that teaches AI coding agents how to work in the repo. Phase 1 is read-only (reports only). Phase 2 applies fixes (guidance files only unless the user explicitly includes application code).
Repo layout varies. Discover actual paths first (Glob **/CLAUDE.md, AGENTS.md, .cursor/, .agents/, docs/) — do not assume the examples below exist in every project.
Complements skills such as context-engineering (maturity and architecture) and update-docs (doc sync after code changes). This skill is the operational playbook for a full guidance health check.
Non-negotiable rules
- Two phases, never merged. Phase 1 subagents must not edit guidance. Phase 2 subagents must verify each finding before fixing; skip false positives.
- Many narrow subagents, not one generalist. Split by folder/domain. Run Phase 1 lanes in parallel; run Phase 2 one subagent per Phase 1 report, in parallel when scopes do not overlap. Ensure at least one or two lanes cover areas with the most recent codebase changes so guidance there is checked against live code, not only static folder templates.
- Guidance-only by default. Phase 2 edits agent instruction files, docs, IDE rules, skills metadata, task/index files — not application source unless the user asks.
- Verify against the live repo. Every finding needs evidence:
Glob/Grep/Read, manifest scripts (package.json, Makefile, etc.), routes, installed skill/agent paths.
- Concise agent guidance. Remove ambiguity and stale claims; do not bloat files with copied checklists from external skills.
- Ephemeral audit folder. Reports live in a dated review folder until remediation is accepted; then delete the whole folder (user typically approves before Phase 2 and again before cleanup).
- Subagent model (Cursor). Launch every Phase 1 and Phase 2 subagent on Composer 2.5 (
composer-2.5) unless the user names a different model. If the host offers a newer Composer generation, use that latest Composer model instead. Do not omit the model pin on Cursor Task/subagent calls unless the user explicitly asks you to.
When to use
- User asks to audit context, agent guidance, or documentation for agents.
- Repeated agent mistakes trace to contradictory or stale module docs.
- After large refactors, strategy doc moves, or skill/agent path changes.
- Before standardizing agent discovery across Cursor, Claude Code, or other tooling.
Review directory
Pick a location your repo already uses for audits (or create one under docs/reviews/):
docs/reviews/context-guidance-audit-YYYY-MM-DD/
├── SYNTHESIS.md # Optional: parent writes after Phase 1 only
├── 01-<scope-slug>.md
├── 02-<scope-slug>.md
└── ...
Use zero-padded numbers and stable slug names so Phase 2 maps 1:1 to reports.
Phase 1 — Audit (read-only)
Orchestrator
- Create the dated review directory.
- Discover guidance artifacts (root
CLAUDE.md / AGENTS.md / CODEX.md, nested **/CLAUDE.md, .cursor/rules/, .agents/skills/, .claude/agents/, docs trees).
- Identify recently changed areas (e.g.
git log --since=…, recent merges, active branch diff, or user-stated focus). Map changed code paths to nearby guidance (**/CLAUDE.md, docs, skills) — at least one or two Phase 1 scopes must include those areas, even if you otherwise use a standard lane split.
- Choose 4–8 parallel audit scopes — disjoint folders/domains, biased toward recent-change coverage where it matters. See references/example-scope-splits.md for sample lane patterns (including one real Next.js monolith example).
- Launch one subagent per scope with:
- Model: Composer 2.5 (
composer-2.5), or the latest Composer generation available in Cursor if newer.
- Explicit read-only instruction (
Do NOT fix anything).
- Output path for the report file (subagent must write the file — use a subagent type with write access; read-only explorers require the parent to persist output).
- Report template (below).
- Instruction: Severity | Location | Issue | Recommended change for verified issues only.
- Wait for all Phase 1 subagents before synthesis or Phase 2.
- Optionally write
SYNTHESIS.md (top issues, batch fix order). Do not fix guidance yet unless the user waives Phase 1 separation.
Phase 1 report template
# <Scope Title> Audit
## Summary
(2–4 sentences)
## Findings
| Severity | Location | Issue | Recommended change |
| High/Medium/Low | file:section | ... | ... |
## Positive observations
## Suggested fix priority order
What Phase 1 subagents check
| Category | Examples (adapt to your stack) |
|---|
| Contradictions | Root vs module context files; UI layer vs API layer rules |
| Stale facts | “Phase N” or migration notes vs shipped code; wrong script names in docs |
| Broken references | Missing files, moved paths, wrong line numbers, dead skill names |
| Ambiguity | Broad globs (src/**) that include files the rule was not meant for |
| Discovery | Symlinks, duplicate agent trees (.cursor/ vs .claude/), skill invoke strings |
| Strategy drift | Product/docs language vs canonical strategy or north-star docs |
| Version claims | Documented framework/library versions vs lockfile or manifest |
Phase 2 — Remediate (verify + fix)
Gate
Wait for user permission after Phase 1 (and optional synthesis) unless they already asked to “audit and fix.”
Orchestrator
- Launch one subagent per Phase 1 report, same scope boundary — each on Composer 2.5 (
composer-2.5) or the latest Composer generation available in Cursor if newer.
- Each subagent:
- Reads its audit report.
- Re-verifies each finding.
- Applies minimal edits in scope.
- Appends
## Remediation log to the same report (verified / fixed / skipped + paths).
- Wait for all Phase 2 subagents before declaring done.
- Run repo-appropriate verification when links or paths changed (doc link linter, markdown lint, symlink checks — use whatever the project documents).
- After user accepts: delete the audit folder.
Phase 2 edit principles
- Prefer one authoritative home for a rule; link elsewhere (dedupe parent vs module docs).
- Replace brittle fixed counts with pointers to canonical helpers or modules (never
"N agents", "N skills", or version snapshots in guidance).
- Skill/agent IDs — do not swap on weak evidence. Missing from
.claude/skills/ alone is not enough. Check .agents/skills/, plugin marketplaces, Cursor plugin cache, and agent frontmatter before changing resend, email-best-practices, tailwind-v4-shadcn, or IDs listed on supabase-expert / resend-email-expert Only replace when proven removed (e.g. documented registry deletion, file deleted, upstream rename). When unsure, skip and log deferred — do not substitute a local-only skill.
- Add banners for superseded docs; link to current strategy or index — do not rewrite historical body text unless asked.
- For modular strategy or policy docs: fix links and navigation only unless the user asked to rewrite content.
Deferred items
Log out-of-scope follow-ups in the remediation log; do not expand scope mid-flight.
Choosing audit scopes
Split so each lane owns a disjoint set of guidance files. Typical patterns (names and paths will differ):
| Lane type | Often includes | Look for |
|---|
| Root + docs index | Root agent file, docs/README, top-level docs policy | Broken links, duplicate indexes, strategy hierarchy |
| App / routes layer | Route or page module context files | Handler vs page rules mixed, stale route paths |
| Library / domain layer | Service, lib, or component module context files | Stale phase notes, wrong canonical APIs |
| Tasks + agents + tooling | Task trackers, agent dirs, IDE rules, slash commands | Symlink breaks, script name drift, discovery conflicts |
| Maintainer / architecture guides | Coding guides, ADRs, workflow docs | Pre-implementation docs vs live code |
| Docs site / published docs | Static site config, content inventory | Inventory vs on-disk content |
| Skills inventory | Skill references across all guidance files | Fictional skill names, plugin vs local skill mismatch |
| Product / ops / user docs | User guides, runbooks, API overview | UI labels vs app, wrong URLs, API table gaps |
Adjust lane count (4–8). Merge or split based on repo size. Do not let a template split skip hot paths: if recent work touched specific modules, routes, or docs, dedicate at least one lane (or explicit checklist items inside a lane) to cross-check guidance there against the changed code. Example splits: references/example-scope-splits.md.
Subagent dispatch pattern
Cursor: pin Composer 2.5 (composer-2.5) on every Phase 1 and Phase 2 subagent unless the user specifies otherwise; if a newer Composer model is available in the host, use the latest Composer generation instead. Non-Cursor hosts: omit explicit model pins unless the user requests them.
Phase 1 prompt skeleton:
Audit [SCOPE PATHS] for confusion, contradictions, stale guidance.
Pay extra attention to [RECENT CHANGE PATHS IF IN SCOPE].
Do NOT fix anything. Verify with Glob/Grep/Read against the live repo.
Write report to [REVIEW_DIR]/NN-slug.md
Use the standard findings table. Only verified issues.
Phase 2 prompt skeleton:
Read [REVIEW_DIR]/NN-slug.md
Verify each finding. Fix verified issues in [SCOPE ONLY] — guidance files only.
Optimize for clear, concise AI-agent guidance. Append ## Remediation log to the report.
Use a write-capable subagent when reports must be saved on disk; use read-only exploration only if the orchestrator persists output.
Orchestrator checklist
Phase 1
Phase 2
Anti-patterns
- Single subagent full-repo audit — misses cross-layer contradictions; overloads context.
- Fix during Phase 1 — loses verified finding list and user review gate.
- Assume this repo matches an example layout — always discover paths first.
- Paraphrase modular policy/strategy body text — prefer links and banners.
- Paste external skill checklists into agent files — bloat; sync durable repo-specific rules only.
- Leave audit folders forever — delete after remediation.
- Replace plugin skill IDs because
.claude/skills/ lacks a symlink — check .agents/skills/, plugins, and cache first; user-facing agents often list marketplace skills intentionally.
- Hardcode agent/skill totals (
"25 Project Agents", "38 skills") — point to .claude/agents/ or skill trees instead.
Related skills (if present in the repo)
- context-engineering — maturity audit, bootstrap, diagnose
- update-docs — doc updates driven by code changes
- docs-maintainer — docs folder hygiene and index sync
- code-review-command — subagent-driven code review (different artifact layout)
