Audit Skill

What this does

Audits a single folder for correctness. Reads every in-scope file (via a parallel fleet of read-only agents for large folders, or a single pass for small ones), fact-checks (internal consistency always; targeted web verification for externally-checkable claims), validates file structure and vault hygiene, then writes ONE tiered findings report — _audit-YYYY-MM-DD-HHMM.md — inside the reviewed folder. It NEVER modifies the reviewed files; after reporting it OFFERS to fix issues with per-change confirmation.

Arguments

• /audit <folder-path> [focus instructions]
• <folder-path>: relative to vault root, e.g. 15-workspaces/<some-workspace> or 10-projects/<some-project>. Quotes optional.
• Trailing free text: an optional FOCUS DIRECTIVE, threaded to every agent.
• No path given: default to the current note's parent folder and confirm. If no current note, ask for a path.

Steps

Phase 0 — Map & plan

1. Resolve the folder path relative to vault root. If it does not exist, report and suggest the closest-matching folders (Glob); stop.
2. If the path is a single file → set mode = SINGLE-FILE and review just that file in Phase 1.
3. If the path is a protected/excluded area (_meta/, 40-archive/, attachments/, .obsidian/, .git/) → warn and require explicit confirmation before continuing.
4. Enumerate every file under the folder (Glob <folder>/**/*) and classify each:
   • KNOWLEDGE NOTE — user-authored .md → deep review.
   • RAW/GENERATED DATA — under _raw/, or .json/.xml/.csv/data dumps/generate.py → light review (structure/sanity/spot-check only).
   • CONFIG/SCAFFOLD — CLAUDE.md, .claude/**, settings*.json, .gitkeep, templates → context only.
   • BINARY/ATTACHMENT — images, PDFs, etc. → note presence; read only if the focus directive points at them.
   • PRIOR REPORT — _audit-*.md / _review-*.md → SKIP (never audit our own output).
5. Read shared context ONCE, to bundle into every agent brief: the folder's own README.md/CLAUDE.md if present, _meta/orient.md, _meta/tags.md (approved vocabulary), _meta/profile.md only if facts about the user are in scope, and notes wikilinked from the folder's key files.
6. Choose mode by knowledge-note count:
   • ≤ ~8 notes → SINGLE-PASS (no fan-out): the coordinator reviews all files directly.
   • 9–40 notes → FAN-OUT: group files into chunks (by subfolder; split big subfolders into batches of ~10–20 files). Cap at ~6–10 parallel agents.

   • ~40 notes OR many subfolders → print a REVIEW PLAN (file counts by class, number of agents, deep-vs-light split, focus directive) and ask for ONE confirmation before dispatching.

7. If there are zero KNOWLEDGE NOTES and zero RAW/DATA files in scope, report "Nothing to audit in <folder>." and stop. A folder with only data/binaries (no knowledge notes) gets a light structural audit, not a deep content review. Otherwise, print a short scope summary: folder, file counts by class, chosen mode, focus directive.

Phase 1 — Review (read-only)

8. FAN-OUT mode: dispatch one agent per chunk IN PARALLEL (a single message with multiple Agent calls). Use a read-only agent type (Explore or general-purpose) and tell it explicitly NOT to edit or write any file. SINGLE-PASS / SINGLE-FILE mode: the coordinator performs the same review inline.
9. Give each agent this BRIEF:
   • Inputs: the folder map, the shared context, the focus directive, and its assigned file list.
   • Review each assigned file across ALL lenses:
     • FACTUAL ACCURACY — flag wrong claims. For claims that are externally checkable or that you are unsure about, DO NOT web-search; instead mark them verify: web so the coordinator batches them in Phase 2.
     • INTERNAL CONSISTENCY — check math (credit totals, sums, dates), within-file contradictions, and claims that contradict the shared context.
     • VAULT HYGIENE — frontmatter present and valid (type, date, status, tags); every tag ∈ _meta/tags.md; wikilinks used (flag markdown links [text](path)); source: present where content is derived.
     • WRITING QUALITY — clarity, structure, redundancy, broken formatting, dead TODO/placeholder text.
     • LOCAL STRUCTURE — file naming/placement oddities within the chunk.
   • Return STRUCTURED FINDINGS ONLY (no prose essays), one record per issue: {file, location, severity: Critical|Important|Minor, confidence: High|Med|Low, lens, issue, suggestion, verify: web?} plus a one-line chunk summary. Do not modify any file.
10. Collect all findings and all verify: web claims.

Phase 2 — Synthesis & verification

11. Whole-folder checks (coordinator):
    • BROKEN WIKILINKS — for every [[link]] in the folder, confirm the target note exists (in-folder first, then vault-wide via Glob). List danglers.
    • CROSS-NOTE CONTRADICTIONS — conflicting facts/numbers/dates across different notes.
    • DUPLICATES — the same topic covered in two notes → suggest a merge.
    • STRUCTURE — orphan files, misfiled notes, notes referenced but missing, naming inconsistency, overall folder organization.
    • TAG-VOCAB ROLLUP — collect every tag used; flag any not in _meta/tags.md as SUGGESTIONS (never auto-add).
12. WEB VERIFICATION — for the verify: web claims only, batch-verify with WebSearch/WebFetch. Record each as confirmed / wrong / unverifiable WITH a source URL. If web tools are unavailable, mark every such claim "unverified — no web access." Never guess.
13. De-duplicate findings; assign final severity + confidence; group by file.

Phase 3 — Report

14. Compute the path <folder>/_audit-<YYYY-MM-DD-HHMM>.md. Read templates/audit-report.md and substitute:
    • {{date}} → now (YYYY-MM-DD HH:MM); {{scope}} → folder path; {{mode}} → single-pass / fan-out (N agents) / single-file; {{focus}} → the focus directive or —.
    • {{verdict}} → 1–3 sentence overall health + headline issues.
    • {{scorecard}} → one table row per dimension (Factual / Consistency / Hygiene / Structure / Writing): | <dimension> | ✅|⚠️|❌ | <count> |.
    • {{critical}}, {{important}}, {{also-noted}} → bulleted findings; each: file + location, what is wrong, suggested fix, evidence/citation. Empty section → —.
    • {{fact-check-log}} → one line per web-verified claim: claim → confirmed/wrong/unverifiable + source URL.
    • {{coverage}} → what was deep-reviewed vs. light vs. skipped, with file and agent counts.
15. Write the report file. This is the ONLY file the skill writes.
16. Post a chat summary: verdict + scorecard + the top 3–5 issues + a [[_audit-…]] wikilink to the full report.
17. Offer: "This was read-only — I changed nothing. Want me to fix any of these? I'll confirm each change before writing." If the user says yes, fix issues ONE BATCH AT A TIME with confirmation, honoring the Rules below. Fixing is a separate, opt-in follow-up, not part of the audit.

Rules

• READ-ONLY by default. Agents get no edit/write permission. The coordinator writes exactly ONE file: the audit report. Reviewed files are never modified during an audit.
• Never auto-add tags. Tag-vocabulary violations are reported as suggestions for the user to approve in _meta/tags.md.
• Cite a source URL for every externally-verified fact. Mark anything unverifiable as such — never fabricate a citation.
• Skip prior _audit-*.md / _review-*.md files when enumerating — never audit our own output.
• Warn + confirm before auditing _meta/, 40-archive/, attachments/, .obsidian/, .git/.
• The report note uses type: audit, tags: [audit]. Never tag it #review (that means "flagged for weekly review," not "is an audit report").
• Degrade gracefully: if web/MCP tools are unavailable, complete the audit and mark affected items "unverified" rather than failing or guessing.
• Any post-report fixing confirms each change, never deletes without explicit confirmation, and never edits _meta/profile.md or _meta/memory.md without permission.
• Use [[wikilinks]] in the report and chat summary, never markdown links.