Audit Automation Gaps

Pre-computed context

Automation inventory: !bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/scripts/inventory.sh" 2>/dev/null || echo "inventory unavailable"

Purpose

Audit the repo's automation landscape and identify genuine gaps, not surface-level "you don't have X" observations, but evidence-backed gaps where no mechanism in the enforcement hierarchy covers the concern.

Design principle: most "missing automation" gaps are already covered by higher enforcement levels (compiler, analyzers, build-time checks, architecture tests, behavioral rules). This skill's job is to prove a gap exists before recommending a solution. The default verdict is REJECT, not PASS.

The enforcement hierarchy (strongest first): compiler settings → static analyzers/linters → architecture tests → unit/integration tests → git hooks → Claude Code hooks → code review → documentation/behavioral rules. A consuming repo that documents its own hierarchy in CLAUDE.md or rules files overrides this default ordering, so read and use theirs.

Adapting to your environment (graceful degrade)

This skill is self-contained. Where a phase names an adjacent capability, such as a research skill, an implementation-planning skill, a work-item tracker, or an outcome verifier, treat it as optional: if your setup provides an equivalent, use it; otherwise follow the inline guidance, which stands on its own. Adjacent skills cover neighboring questions: the sibling audit skill (are the config FILES correct?) and the audit skill in the claude-memory plugin (is the instruction layer healthy?).

Arguments

Parse $ARGUMENTS for:

• --recommend-only: Run evaluation phases only, skipping implementation. Default behavior
• --implement: After presenting validated recommendations, implement user-chosen items sequentially
• Category filter (hooks, mcp, skills, subagents, scheduled): Limit to a specific automation type. Default: all

Track progress

For any deep-dive run (Phases 1-4), keep a phase checklist and tick each phase + every anti-noise doctrine check as it completes, either in-response or by copying ${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/templates/checklist.md into wherever the consuming repo keeps working task notes. Phase 4 is SKIPPED in default --recommend-only mode.

Phase 1: Discover Candidates (Self-Generated)

Analyze the current automation landscape directly, with no external recommender dependency.

1.1 Inventory Current State

Run bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/scripts/inventory.sh", then read:

1.2 Gap Analysis

For each automation category, systematically check for gaps using the category-specific checklists in context/gap-analysis.md: Hooks (formatter exists? fast enough? higher enforcement already covers?), MCP Servers (configured? CLI equivalent? service in use yet?), Skills (skill exists? frequency? simpler mechanism?), Subagents (value over hook/skill? isolation help? plugin exists?), Scheduled (tracked in the repo's work-item tracker? Dependabot/CI covers? right durability model?).

1.3 Generate Candidate List

Produce a numbered list of candidates with category and one-line rationale. Target 5-10 candidates. Cast a wide net, the quality gates will filter. Include borderline items; it's better to evaluate and reject with evidence than to silently exclude.

Phase 2: Deep-Dive Each Candidate

For each candidate, execute the evaluation workflow. Batch the Explore phase (read all configs once), then evaluate candidates sequentially.

2.1 Explore (Local Codebase)

For each candidate:

• Read the relevant config/code: the specific files that would be affected
• Check the enforcement hierarchy: walk up from the weakest level (docs) to the strongest (compiler). Stop when you find coverage. Document which level covers it
• Check incident history: git log --grep for related problems. Count incidents vs total commits for frequency
• Measure performance: if the candidate involves a CLI tool as a hook, time it:

time <tool-command> 2>&1 | tail -5

PostToolUse hooks must complete in <15-30s. A slower tool fits a per-edit hook only as a non-blocking command hook with async: true.

2.2 Research (Targeted, Parallel)

Launch parallel research agents for candidates that survive initial Explore (weren't immediately disqualified by performance or existing enforcement). Group related queries to minimize agent count.

Per-candidate research questions by type:

Verify Claude Code mechanisms against official docs (code.claude.com/docs/en/hooks, code.claude.com/docs/en/mcp); use web search for tool performance and community practices. Delegate the fetches and keep the verdicts: agents gather evidence, and the gate decisions in 2.3 stay in the main context.

2.3 Vet / Validate (Quality Gates)

A candidate fails if ANY gate triggers:

These gates answer should we mechanize. Whether a candidate can be, and how far up the hierarchy it climbs, is a separate enforceability question: the Not scriptable gate maps to concerns no hook type reaches, Already enforced to a deterministic finding already escalated. prompt and agent hooks do evaluate reasoning-only concerns, agent experimentally.

Produce a verdict per candidate:

• PASS: clears all gates, provides genuine value
• CONDITIONAL PASS: value exists but only under specific conditions (document the condition)
• REJECT: fails one or more gates (cite which gates and evidence)

Phase 3: Present Results

Summary Table

| # | Candidate | Category | Verdict | Key Evidence |
|---|-----------|----------|---------|--------------|
| 1 | ... | Hook | REJECT | [gate]: [evidence] |
| 2 | ... | Skill | PASS | No existing coverage, [frequency]% of commits |

Detailed Verdicts

For each candidate, provide:

• Verdict with gate results
• Evidence (timing data, git history counts, enforcement mechanisms found)
• For PASS/CONDITIONAL PASS: implementation plan (files to change, effort estimate, test strategy)

Order by value/impact, highest value first. Value = frequency × severity × ease of implementation.

Maturity Assessment

End with a one-paragraph assessment of the repo's automation maturity: what's well-covered, what the genuine gaps are (if any), and whether the current automation investment level is appropriate for the project stage.

If items pass: "Which items would you like to implement? I'll work through them sequentially."

If no items pass: State that clearly. A clean bill of health is a valid outcome.

Phase 4: Implement (if --implement or user requests)

For each user-selected item:

1. Explore: re-read current state (may have changed since evaluation)
2. Research + Validate: verify the implementation approach against current docs
3. Plan: detailed implementation steps
4. Implement: execute with incremental validation and commit checkpoints
5. Test: verify the automation works (run hooks, test skills, etc.)
6. Review: self-review for consistency with existing patterns
7. Verify: build/test the repo if code changed, confirm no regressions

Route steps 2-7 through the consuming environment's own workflow skills when it has them; the inline steps stand on their own otherwise.

Quality Principles

Principles that govern every verdict:

1. The enforcement hierarchy is your first check. Most "gaps" are covered by the compiler-through-git-hooks levels
2. Measure, don't assume. Time every tool before recommending it as a hook. A formatter looks perfect until you measure 15+ seconds per file
3. Check incident history. Zero incidents across 100+ commits is strong evidence the problem doesn't exist in practice
4. Behavioral rules are valid enforcement. A rule in CLAUDE.md is legitimate coverage; not everything needs a hook or script
5. YAGNI is a quality gate, not laziness. Automation for a task at 4% frequency is premature
6. Premature is worse than missing. Adding a database MCP before a database exists, or scheduling before CI exists, creates maintenance burden for zero value
7. A clean bill of health is a valid outcome. Not finding gaps means the automation is mature; don't manufacture recommendations to justify the audit