name	audit-investigation
description	Use when investigating config file discrepancies during audit. Spawns config agents in waves to compare template standards against actual files. READ-ONLY analysis - agents report findings but make no changes.

Audit Investigation Skill

ROOT AGENT ONLY - Called by /audit command during investigation phase.

Purpose: Investigate configuration discrepancies by comparing templates to actual files

Trigger: After execution plan approved, before user resolution decisions

Input:

execution_plan - waves of (agent, file) pairs from planning phase
repoType - repository type for context
repos[] - list of repositories in scope

Output:

discrepancies[] - all findings with severity, location, expected vs actual
summary - aggregate stats by severity and file count

Workflow Steps

1. Parse Execution Plan

Extract waves from execution plan
Each wave contains max 10 (agent, file) pairs
Waves execute sequentially, agents within wave execute in parallel

2. Execute Investigation in Waves

For each wave:

Step	Action
a. Spawn config agents	Parallel invocation (max 10)
b. Agent reads template	From agent's skill templates/ directory
c. Agent reads actual file	From repository using Read tool
d. Agent compares field-by-field	Template rules vs actual config
e. Agent reports discrepancies	Line numbers, expected/actual, severity

3. Aggregate Results from All Waves

For each agent result:
  a. Extract discrepancy findings
  b. Normalize format:
     {
       file: "path/to/file",
       line: 42,
       field: "extends",
       expected: "@metasaver/eslint-config",
       actual: "eslint:recommended",
       severity: "critical" | "warning" | "info",
       agent: "eslint-agent",
       message: "Config extends incorrect base"
     }
  c. Add to master discrepancies array

4. Sort by Severity

Priority order:
  1. critical - Blocks compliance, must fix
  2. warning - Recommended fix, impacts quality
  3. info - Optional improvement, style preference

Within same severity: alphabetical by file path

5. Generate Summary

{
  "total_files": 12,
  "total_discrepancies": 47,
  "by_severity": {
    "critical": 8,
    "warning": 24,
    "info": 15
  },
  "by_agent": {
    "eslint-agent": 12,
    "prettier-agent": 8,
    "typescript-agent": 15,
    "vite-agent": 12
  }
}

6. Return Structured Output

Complete list of discrepancies for resolution phase
Summary for user presentation
NO CHANGES MADE - all read-only investigation

Agent Invocation Pattern

Parallel Wave Execution:

Wave 1 (10 agents):
  Task 1: subagent_type="core-claude-plugin:config:eslint-agent"
    Prompt: "Audit .eslintrc.js in /path/to/repo against your template. Report discrepancies."

  Task 2: subagent_type="core-claude-plugin:config:prettier-agent"
    Prompt: "Audit .prettierrc in /path/to/repo against your template. Report discrepancies."

  ... (up to 10 parallel)

Wait for all Task 1-10 to complete, collect results

Wave 2 (remaining agents):
  ... repeat pattern

Agent Instructions:

Each config agent receives:

Target file path to audit
Repository context (type, location)
Instruction: "READ-ONLY audit - compare template to actual, report discrepancies"
Expected output format (JSON with discrepancies array)

Severity Classification

Severity	Criteria	Examples
critical	Breaks standards, blocks functionality	Missing required plugin, incorrect parser, wrong extends chain
warning	Impacts quality, recommended fix	Suboptimal rule config, missing recommended plugin, style inconsistency
info	Optional improvement	Comment formatting, property order, alternative valid config

Agent Responsibility: Each config agent determines severity based on template rules.

Output Format

Discrepancies Array:

[
  {
    "file": "packages/web/.eslintrc.js",
    "line": 3,
    "field": "extends",
    "expected": ["@metasaver/eslint-config"],
    "actual": ["eslint:recommended"],
    "severity": "critical",
    "agent": "eslint-agent",
    "message": "Config must extend @metasaver/eslint-config for standards compliance"
  },
  {
    "file": "packages/api/prettier.config.js",
    "line": 5,
    "field": "semi",
    "expected": false,
    "actual": true,
    "severity": "warning",
    "agent": "prettier-agent",
    "message": "Semicolons should be disabled per house style"
  }
]

Summary Object:

{
  "total_files": 12,
  "total_discrepancies": 47,
  "by_severity": {
    "critical": 8,
    "warning": 24,
    "info": 15
  },
  "by_agent": {
    "eslint-agent": 12,
    "prettier-agent": 8,
    "typescript-agent": 15,
    "vite-agent": 12
  },
  "files_with_issues": [
    "packages/web/.eslintrc.js",
    "packages/api/prettier.config.js",
    "packages/web/tsconfig.json"
  ]
}

Error Handling

Scenario	Action
File not found	Report as critical: "Missing required config file"
Agent crashes	Log error, continue with remaining agents, flag for user review
Template missing	Report as critical: "Agent template unavailable - cannot audit"
Parse error	Report as critical: "Config file syntax invalid"
No discrepancies	Return empty array for that file (success)

Graceful Degradation: If some agents fail, continue with successful agents and report partial results.

READ-ONLY Guarantee

Critical Rules:

NO Write tool calls - investigation only uses Read tool
NO Edit tool calls - no modifications to any files
NO file creation - only analyze existing files
NO template updates - templates are read-only reference
Agents report findings in memory only (JSON output)

Verification: Command should validate no file system changes occurred during investigation.

Wave Management

Why Waves?

Control parallelism (max 10 agents per wave prevents resource exhaustion)
Sequential wave execution ensures results collected before next wave
Enables progress tracking (wave 1/3 complete)

Wave Size Optimization:

Total Agents	Waves	Agents per Wave
1-10	1	1-10
11-20	2	10, remaining
21-30	3	10, 10, remaining

Example:

Execution plan: 27 (agent, file) pairs

Wave 1: agents 1-10 (parallel)
Wave 2: agents 11-20 (parallel)
Wave 3: agents 21-27 (parallel)

Total execution time ≈ max(wave_durations)

Integration with Other Skills

Before This Skill:

/skill requirements-phase - gathers requirements
/skill planning-phase - creates execution plan with waves
/skill hitl-approval - user approves plan

This Skill:

Executes investigation per approved plan
Spawns config agents in waves
Collects all discrepancies
Sorts and aggregates results

After This Skill:

/skill audit-resolution - presents findings to user for decisions
User chooses: apply template, update template, ignore, or custom action

Agent Routing Matrix

Config Type	Agent	Template Location
.eslintrc.js	eslint-agent	skills/config/code-quality/eslint-config/templates/
.prettierrc	prettier-agent	skills/config/code-quality/prettier-config/templates/
tsconfig.json	typescript-agent	skills/config/workspace/typescript-configuration/templates/
vitest.config.ts	vitest-agent	skills/config/build-tools/vitest-config/templates/
tailwind.config.js	tailwind-agent	skills/config/workspace/tailwind-config/templates/
pnpm-workspace.yaml	pnpm-workspace-agent	skills/config/build-tools/pnpm-workspace-config/templates/
.editorconfig	editorconfig-agent	skills/config/code-quality/editorconfig-config/templates/

Agent Discovery: Planning phase maps files to agents using /skill agent-check.

Example Execution