# System Audit > Use when you need to run parallel audits across skills, hooks, agents, rules, and conventions. - Skill: `lhh666-6/system-audit` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add lhh666-6/system-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/lhh666-6/system-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: lhh666-6 (https://skillmd.com/u/lhh666-6) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/lhh666-6/system-audit --- # Maintenance Sweep > System-wide health check using agnix lint + a deterministic Python facts script + 3 parallel judgment sub-agents. Produces a consolidated report at `log/audits/system-audit-YYYY-MM-DD.md`. **Report-only — never modifies any files.** > > **Architecture note (2026-05-23):** Sub-agents previously handled counts, broken-link detection, ecosystem inventory, and friends-repo file checks (SA1/SA4/SA5/SA7). They were unreliable — rolling their own counters, resolving links against the wrong CWD, recursing into the wrong directories — and produced false-positive findings that wasted triage cycles. Those four are now replaced by `.scripts/system_audit_facts.py`, which uses `count_inventory.py` as ground truth and resolves links against the source file's directory. The 3 remaining sub-agents (SA2 Bibliography, SA3 Conventions, SA6 Skill Quality) handle genuinely judgment-heavy work that can't be reduced to a script. ## When to Use - Periodic system hygiene (monthly or after major changes) - When the user says "maintenance sweep", "system health check", "audit my setup" - After adding/removing skills, hooks, agents, or rules - Before presenting the system to others (ensure everything is consistent) ## Overview 1. **Lint** — run `npx agnix .` + skill-numbering lint + review-agent logger-gate lint 2. **Facts** — run `.scripts/system_audit_facts.py all --json` (deterministic: counts, docs, ecosystem, friends repo) 3. **Dispatch** — launch 3 judgment sub-agents in parallel via the Task tool (SA2/SA3/SA6) 4. **Collect** — gather facts JSON + sub-agent findings 5. **Consolidate** — merge into a single timestamped report 6. **Present** — show key findings to the user **Python:** Always use `uv run python` or `uv pip install`. Never bare `python`, `python3`, `pip`, or `pip3`. Include this in sub-agent prompts. ## Autonomy Per the global `--autonomous` / `-y` convention in `~/.Codex/rules/phased-work.md` § "Autonomy flag convention". Invoke as `/system-audit --autonomous` (or `-y`). When set: - **No inter-phase pauses** — Lint → Dispatch → Collect → Consolidate → Present chain end-to-end. - **No `AskUserQuestion` mid-run** — sub-agent count defaults to 3 (SA2/SA3/SA6), all sub-agents launch in parallel without confirmation. - **No interim "review and continue" pauses** between dispatch and consolidation. - **Sub-agent forbid-list still applied** — all 3 sub-agents are read-only (no edits to skills/hooks/agents/rules during the audit). - **Report-only invariant preserved** — `--autonomous` does NOT change the skill's read-only nature; it only suppresses confirmation prompts. No fixes are ever applied. - **Single end-of-run report** at `log/audits/system-audit-YYYY-MM-DD.md` is the only mandatory user-facing output. This is one of the safer skills to run autonomously — it's read-only by design, sub-agents have no write access to the system, and the output is a single timestamped report that you can review afterward. Recommended for scheduled monthly runs via `/scheduled-job`. Recommended invocations: ``` /system-audit --autonomous # full sweep, end-to-end /system-audit -y # short form ``` --- ## Phase 0: Pre-flight Lints Two fast lint passes run in the main context before sub-agent dispatch. Both are summary-only — full findings feed into the final report. ### 0.1 agnix lint Run `npx agnix .` and capture the summary line. **Pass criteria:** 0 errors. Warnings are informational only. If errors > 0, list them in the report under an **agnix Lint** section. These are structural issues in skill/hook/agent frontmatter that should be fixed. Config lives in `.agnix.toml` at project root — known false positives are already suppressed. ### 0.2 skill-numbering lint Run `uv run python scripts/lint-skills.py` and capture the summary line. **Pass criteria:** 0 findings. Findings indicate phase-numbering smells, frontmatter typos, or stale cross-skill phase references. Reference: [`skills/_shared/skill-template.md`](../_shared/skill-template.md) § Anti-patterns. If findings > 0, list them in the report under a **Skill-Numbering Lint** section. The linter explains each rule (R1–R9) inline. ### 0.3 review-agent logger-gate lint Run: ```bash grep -E "^After producing (DOMAIN-REVIEW|CODE-REVIEW|your verdict|your referee|the verification)" .Codex/agents/*.md ``` **Pass criteria:** 0 matches. Any match means a review-agent definition is using the stale/fragile logger-gate intro pattern that was fixed by the 5-agent patch (commit `23ebcfff`, 2026-05-17). The fragile pattern conditions the `review-state-log.sh` call on producing a stale top-level filename (`DOMAIN-REVIEW.md`-style) or a soft generic phrase (`"your verdict"`, `"the verification"`); when orchestrators like `/review-cluster` send "Return findings as a structured list, NOT a file write", the gate fails and the helper never fires — leaving a logger gap detectable by `/review-recap`. If matches > 0, list them in the report under a **Review-Agent Logger-Gate** section with the suggested replacement intro: > Write [your report] to `reviews//.md` (`mkdir -p reviews//` first). Then append a row to the project's `REVIEW-STATE.md` so `/review-recap` can render the run. Use the shared helper: Reference pattern: see `paper-critic.md` line ~432 (already patched). --- ## Phase 1: Deterministic Facts Run the deterministic facts script in the main context. This replaces the four count/link/inventory sub-agents that were unreliable. ```bash uv run python .scripts/system_audit_facts.py all --json > /tmp/system-audit/facts.json ``` What this covers (all deterministic — no LLM judgment needed): | Section | Replaces | What it checks | |---------|----------|---------------| | `inventory` | SA1 Inventory Auditor | Skill/hook/agent/rule counts vs `count_inventory.py` ground truth, symlinks, file-extension sanity | | `docs` | SA4 Documentation Freshness | Stale counts in AGENTS.md/README/docs, broken markdown links (resolved against source-file dir, not CWD), `.context/` mtime freshness | | `ecosystem` | SA5 Ecosystem Health | MCP server registry alignment, orphan tool references, CLI tool presence | | `friends` | SA7 Friends Repo Health | Friends-repo skill/rule freshness vs upstream, anonymisation hygiene, install script presence | **Why this is deterministic-only, not a sub-agent:** - Counts have a single source of truth (`count_inventory.py`) — re-rolling them in an LLM produces drift. - Broken-link detection requires resolving relative paths against the source file's directory; sub-agents have variable CWD and produce false positives. - Friends-repo file checks are presence/diff operations, not judgment. If the script fails (exit code != 0), capture stderr in the report under a **Facts Script Failure** section and continue with sub-agent dispatch — the audit degrades gracefully but is no longer authoritative on the deterministic sections. --- ## Phase 2: Dispatch Judgment Sub-Agents Launch 3 in a single message using parallel Task tool calls. Each sub-agent is `subagent_type: Explore`. **Context overflow prevention:** Instruct each sub-agent to keep its returned output concise — summary tables and key findings only (under 500 words). If detailed findings are large, the sub-agent should write them to a temp file (e.g., `/tmp/system-audit/sa-N.md`) and return only the file path + summary. All sub-agents receive shared context (Task Management root, research projects root, category directories). Full shared context block and the 3 sub-agent prompt templates: **[references/sub-agent-prompts.md](references/sub-agent-prompts.md)** Sub-agents at a glance: | # | Name | What it checks | |---|------|---------------| | 2 | Bibliography & Project Hygiene | .bib files, naming, MEMORY.md presence | | 3 | Convention Compliance | LaTeX out/, Overleaf separation, Python env, git health | | 6 | Skill Quality & Overlap | Bloat, staleness, cross-component overlap | Sub-agent numbering retained from the old 7-agent fan-out so prompts and reports stay cross-referenceable. SA1/SA4/SA5/SA7 are now handled by `.scripts/system_audit_facts.py` in Phase 1. --- ## Phase 3: Collect and Consolidate After the 3 sub-agents return, merge their findings + the Phase 1 facts JSON into a single report. ### Report Template Write to `log/audits/system-audit-YYYY-MM-DD.md`: ```markdown # Maintenance Sweep — YYYY-MM-DD ## Dashboard | Area | Source | Status | Issues | |------|--------|--------|--------| | agnix Lint | Phase 0 | | | | Skill-Numbering Lint | Phase 0 | | | | Review-Agent Logger-Gate | Phase 0 | | | | Inventory | Phase 1 (facts) | | | | Documentation Freshness | Phase 1 (facts) | | | | Ecosystem Health | Phase 1 (facts) | | | | Friends Repo Health | Phase 1 (facts) | | | | Bibliography & Projects | SA2 | | | | Conventions | SA3 | | | | Skill Quality & Overlap | SA6 | | | ## agnix Lint ## Inventory Audit ## Documentation Freshness ## Ecosystem Health ## Friends Repo Health ## Bibliography & Project Hygiene ## Convention Compliance ## Skill Quality & Cross-Component Overlap ## Recommended Actions ### Quick Fixes (< 5 min each) - ... ### Medium Effort (5–30 min) - ... ### Larger Tasks (> 30 min) - ... ``` --- ## Phase 4: Present Show the user: 1. The dashboard table 2. Any FAIL-status areas with specifics 3. The quick fixes list 4. Ask if he wants to address any issues now --- ## Error Handling - **Sub-agent timeout:** If a sub-agent doesn't return, note "timed out" in the report and continue with the others. - **Missing directories:** If a category folder is empty or doesn't exist, note "no projects found" rather than erroring. - **Permission issues:** If files can't be read, note "access denied" and continue. ## Integration with Other Skills | Skill | Relationship | |-------|-------------| | `/bib-validate` | Run on projects flagged by the Bibliography Hygiene sub-agent | | `/audit-project-research` | Complements Convention Compliance with deeper per-project checks | | `/update-project-doc` | Fix documentation staleness found by Documentation Freshness | | `/sync-permissions` | Fix symlink issues found by Inventory Auditor | | `/atlas-audit` | Full cross-system audit (local + vault + Paperpile + pipeline) — deeper than this sweep | | `/insights-deck` | Maintenance findings can feed into system insights presentations | | `/repo-doc-audit friends` | Dedicated deep audit for friends-repo — Sub-agent 7 is a quick health check; the audit skill is the full version | | `/sync-friends-repo` | Fix freshness issues found by Sub-agent 7 |