audit-agents

/audit-agents

User-triggered static audit of the .agents/ tree and the per-agent entry points. Treats agent instructions as code that can rot: duplicated rules drift apart, links break when files move, terminology slides ("agent" → "subagent" → "sub-agent"), and skills miss sections that make them harder to invoke consistently. This skill doesn't guess at intent — it enumerates observable problems and asks before touching anything.

Scope

In-scope. Everything under .agents/ plus the repo-root per-agent entry points:

• AGENTS.md — canonical shared contributor core; read natively by Codex, imported by Claude, referenced by Copilot.
• CLAUDE.md — Claude Code entry point; imports AGENTS.md + the Claude overlay at session start.
• .github/copilot-instructions.md — Copilot entry point; points at AGENTS.md.
• .agents/docs/*.md — long-form references imported by skills/agents.
• .agents/agents/*.md — subagent contracts.
• .agents/skills/*/SKILL.md — user-triggered skills.
• .agents/scripts/*.ps1 — PowerShell helpers called by skills.
• .agents/settings.local.json — gitignored personal settings (audit for presence and slnx entry only, not content).

Read-only inspection. The user-level auto-memory directory referenced under this session's # auto memory system-prompt section. The audit reads MEMORY.md and the pointed-to memory files to surface promotion candidates — entries whose content is project-truthy and would benefit other agents on this codebase if lifted into .agents/. Never edit, delete, or rewrite memory files; the user owns that surface.

Out of scope. Project code (Source/, Tests/), other repo metadata (.github/, Build/, Data/), and the baselines clone at ../linq2db.baselines. The audit doesn't second-guess the product itself — only the instructions the agent uses to work on it.

Shared reference material

• Agent rules (branching, Bash, GitHub content): .agents/docs/agent-rules.md
• Claude Code setup (.agents/ layout + .claude symlink, settings precedence): .agents/docs/claude-setup.md
• Slnx sync procedure: .agents/skills/update-slnx/SKILL.md

When to run

Only when the user explicitly asks to audit / lint / review the .agents/ instructions. Do not invoke during unrelated work, even if you notice drift.

Reasonable cadence: once every few weeks, or after a batch of skill/doc changes lands. Running it back-to-back produces a near-empty report — a finding lingering through two audits is the signal that the fix is harder than it looks, not that the skill is under-reporting.

What counts as a finding

Eleven check categories, reported with a per-finding severity (error / warning / info):

Out-of-scope non-findings (deliberately skipped): grammar / typos, stylistic preferences (active vs passive), formatting nits that don't affect rendered output. If the user wants those too, they can ask mid-audit; otherwise skip.

Steps

1. Enumerate the corpus

Batched reads — Glob / Read can run in parallel:

• Glob for .agents/**/*.md and .agents/scripts/*.ps1; read the root entry points AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md.
• Read linq2db.slnx once and extract every <File Path="..."> whose path starts with .agents/ or equals AGENTS.md / CLAUDE.md.
• Read .gitignore to identify gitignored paths under .agents/ (for slnx exemption logic).

Produce three lists: prose-files, script-files, slnx-claude-entries.

2. Run the eleven checks

Checks are mostly independent; run their searches in parallel where you can. Each check produces zero or more finding records of shape:

{
  "id": "<category>-<short-slug>",
  "severity": "error|warning|info",
  "category": "dead-reference|slnx-mismatch|template-gap|duplicated-rule|retired-path|terminology-drift|refactor-candidate|memory-promotion-candidate|wordiness|stale-model-workaround|stale-memory-reference",
  "location": "<file>:<line-range or section>",
  "summary": "<one line>",
  "details": "<2–5 lines of context>",
  "fixKind": "mechanical|creative|manual-only",
  "proposedFix": "<unified diff, instruction, or null when manual-only>"
}

fixKind drives how step 4 offers the patch:

• mechanical — the fix is a single, obvious edit (broken link to updated path, add missing slnx entry, add missing section header). Show as a diff and offer to apply.
• creative — the fix involves a judgment call (how to merge two duplicated rules, which section to promote to the canonical doc). Surface the finding, propose an approach, let the user direct.
• manual-only — the fix needs non-local work (reorganize three files, split a skill). Log the finding, don't auto-patch.

Per-check rules (2a Dead-reference, 2b Slnx-mismatch, 2c Template-gap, 2d Duplicated-rule, 2e Retired-path, 2f Terminology-drift, 2g Refactor-candidate, 2h Memory-promotion, 2i Wordiness, 2j Stale-model-workaround, 2k Stale-memory-reference) live in audit-agents-checks.md. Run them in parallel where possible; each emits zero or more finding records of the shape above.

3. Assemble the report

Group findings by severity, then by category within severity. Display as a numbered list so the user can reference findings by number:

Audit report (17 findings):

Errors (4)
  1. [dead-reference] .agents/skills/review-pr/SKILL.md:42 → .agents/docs/old-review-docs.md (file missing)
  2. [dead-reference] CLAUDE.md:9 → @.agents/docs/agent-rules.md (file exists; check frontmatter casing)
  3. [slnx-mismatch] 2 files on disk not in linq2db.slnx: …
  4. [template-gap] .agents/skills/audit-agents/SKILL.md: missing frontmatter `description:`

Warnings (9)
  5. [duplicated-rule] Branch-naming rule restated with diverging wording in CLAUDE.md:38 and agent-rules.md:14
  …

Info (4)
  …

Per-finding detail line: one-line summary + fixKind tag + path to proposed fix (if any). Keep the top-level list scannable.

4. Offer patches

Per-finding confirmation is the default. For each finding with fixKind: "mechanical", show:

• The current state (2–5 lines of surrounding context).
• The proposed diff (unified).
• Prompt: "apply / skip / batch-mechanical / abort".
  • apply → run the Edit, move to next finding.
  • skip → note as deferred, move on.
  • batch-mechanical → apply all remaining mechanical findings without further prompt; still pause for each creative / manual-only.
  • abort → stop the loop, leave any already-applied edits in place.

For fixKind: "creative", don't propose a single diff. Instead present 2–3 plausible resolutions and ask the user to pick a direction (or write their own). Once direction is clear, re-frame as a mechanical fix and loop back to the per-finding flow.

For fixKind: "manual-only", log the finding and move on — don't block the loop on user input.

5. Apply slnx updates (if any)

If any slnx-mismatch findings were approved for fixing, at the end of the loop invoke /update-slnx rather than hand-editing the slnx. The slnx is owned by that skill's canonical procedure.

6. Report

End with a short summary:

• Applied: N findings (by category)
• Skipped: M findings (by category) — list IDs so the user can re-audit and revisit
• Manual-only: K findings — list IDs
• Still open: any finding that surfaced during the loop but wasn't resolved.

Don't commit. Per .agents/docs/agent-rules.md → Git commit rules, commits need an explicit user request. The audit leaves the working tree staged-or-unstaged for the user to review and commit on their terms.

Don'ts

• Do not run the audit spontaneously or "as a bonus" during unrelated work.
• Do not hand-edit linq2db.slnx directly for slnx-mismatch findings. Always route through /update-slnx.
• Do not auto-apply fixes without confirmation — even mechanical ones. The batch-mechanical option exists for the user to opt in explicitly.
• Do not flag style / grammar / formatting nits that don't affect rendering or semantic meaning. This skill is scoped to drift and decay, not polish.
• Do not edit, delete, or rewrite anything inside the auto-memory directory. The check in audit-agents-checks.md → §2h is read-only — promotion candidates are surfaced as findings; the user decides whether to copy the rule into .agents/ and whether to clean up the memory entry afterwards.
• Do not promote user-type memories. They're personal by definition; lifting them into .agents/ is a category error.
• Do not commit. Changes stay in the working tree until the user asks.