name: audit-comprehensive description: Run all 9 domain audits in staged waves and aggregate results supports_parallel: true fallback_available: true estimated_time_parallel: 65 min estimated_time_sequential: 180 min

Comprehensive Multi-Domain Audit Orchestrator

Version: 3.1 (9-Domain Coverage with Stage 2.5) Time Savings: 65% faster than sequential (250min -> 65min) Stages: 4 stages with 4+3+2+1 agent configuration

What This Does: Spawns 9 specialized audit agents in staged waves (respecting max 4 concurrent limit), with verification checkpoints and S0/S1 escalation, then aggregates findings into a comprehensive report.

When to Use

Tasks related to audit-comprehensive
User explicitly invokes /audit-comprehensive

When NOT to Use

When the task doesn't match this skill's scope -- check related skills
When a more specialized skill exists for the specific task

Overview

This skill orchestrates a complete codebase audit across all 9 domains:

Code Quality (audit-code) - Code hygiene, types, framework patterns
Security (audit-security) - Auth, input validation, OWASP compliance
Performance (audit-performance) - Load times, queries, caching
Documentation (audit-documentation) - README, API docs, architecture
Refactoring (audit-refactoring) - Technical debt, complexity, DRY
Process/Automation (audit-process) - CI/CD, testing, workflows
Engineering Productivity (audit-engineering-productivity) - DX, debugging, offline support
Enhancements (audit-enhancements) - Feature gaps, UX improvements
AI Optimization (audit-ai-optimization) - Token waste, skill overlap, hook latency

Output: Single unified report in docs/audits/comprehensive/audit-YYYY-MM-DD/COMPREHENSIVE_AUDIT_REPORT.md

Orchestration Mode Selection

This skill supports two orchestration modes. Check which is available:

Agent Teams Mode (Preferred when available)

Requires: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.json

When agent teams are enabled, use team-based orchestration:

Lead: Orchestrator + aggregator (you)
Teammate Group A: code + refactoring specialists
Teammate Group B: security + performance specialists
Teammate Group C: documentation + process + engineering-productivity
Teammate Group D: enhancements + ai-optimization specialists

Team advantages: Cross-cutting findings via messages, S0/S1 escalation as team messages, lead handles aggregation directly, no artificial stage boundaries.

Team execution flow:

Lead creates shared task list with all 9 audit tasks
Spawn 4 teammates (grouped by related domains)
Teammates claim and execute audit tasks, messaging lead on S0/S1 findings
Teammates message peers when they find cross-cutting issues
Lead monitors progress, collects results as teammates complete
Lead performs aggregation and deduplication directly
Lead shuts down teammates after all reports collected

Token budget: 250K total for the team. If approaching budget, lead messages teammates to wrap up and collects partial results.

CRITICAL RETURN PROTOCOL for all agents (both team and subagent modes):

Each audit agent writes its report to the output directory
Return ONLY: COMPLETE: [audit-domain] wrote N findings to [output-path]
Do NOT return full findings content -- orchestrator checks completion via file

Fallback: If team formation fails or teammates error out, fall back to the staged subagent execution flow below.

Subagent Mode (Default fallback)

When agent teams are NOT enabled, use the 3-stage subagent execution flow below.

Execution Flow (Subagent Mode)

Pre-Flight Validation
  - Verify all 9 audit skills exist
  - Create output directory
  - Gather baselines (tests, lint, patterns)
  - Load false positives database
        |
        v
Stage 1: Technical Core (4 agents parallel)
  - audit-code, audit-security, audit-performance, audit-refactoring
  - Dependency: All 4 agents are independent -- no ordering required
  - Checkpoint: verify 4 reports + S0/S1 escalation check
        |
        v
Stage 2: Supporting (3 agents parallel)
  - audit-documentation, audit-process, audit-engineering-productivity
  - Dependency: All 3 agents are independent. Stage 2 depends on Stage 1 completion
  - Checkpoint: verify 3 reports
        |
        v
Stage 2.5: Meta & Enhancement (2 agents parallel)
  - audit-enhancements, audit-ai-optimization
  - Dependency: Both agents are independent. Stage 2.5 depends on Stage 2 completion
  - Checkpoint: verify 2 reports
        |
        v
Stage 3: Aggregation (sequential)
  - audit-aggregator -> COMPREHENSIVE_AUDIT_REPORT.md
  - Dependency: Requires all 9 domain reports from Stages 1, 2, and 2.5
        |
        v
Stage 3.5: MASTER_DEBT Deduplication (MANDATORY)
  - Cross-reference findings against MASTER_DEBT.jsonl
  - Skip already-tracked items, flag possibly-related
  - Output: DEDUP_VS_MASTER_DEBT.md
        |
        v
Post-Audit
  - Update AUDIT_TRACKER.md
  - Display final summary
  - Recommend next steps

Details: See reference/WAVE_DETAILS.md for full agent launch instructions, checkpoint scripts, and status display templates.

Pre-Flight Validation

Step 0: Episodic Memory Search (Session #128)

Before running audits, search for context from past audit sessions:

mcp__plugin_episodic -
  memory_episodic -
  memory__search({
    query: ["comprehensive audit", "findings", "patterns"],
    limit: 5,
  });

Why: Compare against previous findings, identify recurring issues, avoid known false positives, track trends.

Step 1: Verify Skills Exist

ls -1 .claude/skills/audit-*/SKILL.md | wc -l
# Should return 9 (excludes audit-comprehensive and audit-aggregator)

If not all present, notify user which audits are missing.

Step 2: Create Output Directory

AUDIT_DATE=$(date +%Y-%m-%d)
mkdir -p docs/audits/comprehensive/audit-${AUDIT_DATE}

Step 2.5: Verify Output Directory (CRITICAL)

AUDIT_DATE=$(date +%Y-%m-%d)
AUDIT_DIR="docs/audits/comprehensive/audit-${AUDIT_DATE}"
AUDIT_PATH=$(realpath "${AUDIT_DIR}" 2>/dev/null || echo "${AUDIT_DIR}")
if [ -z "${AUDIT_DIR}" ] || [ "${AUDIT_PATH}" = "/" ] || [[ "${AUDIT_DIR}" == ".."* ]]; then
  echo "FATAL: Invalid or unsafe AUDIT_DIR"
  exit 1
fi

Why: Context compaction can cause variable loss. Always verify before agent launches.

Step 3: Run Baseline Checks

npm test 2>&1 | grep -E "Tests:|passing|failed" | head -5
npm run lint 2>&1 | tail -10
npm run patterns:check 2>&1 | head -20

Store results in docs/audits/comprehensive/audit-YYYY-MM-DD/baseline.txt for reference.

Step 4: Load False Positives

Read docs/technical-debt/FALSE_POSITIVES.jsonl to pass to aggregator.

Final Report Structure

The COMPREHENSIVE_AUDIT_REPORT.md should contain:

Executive Summary

Total unique findings (after deduplication)
Severity breakdown (S0: X, S1: Y, S2: Z, S3: W)
Top 3 cross-domain insights
Recommended fix order
Effort estimate (total hours)

Priority-Ranked Findings (Top 20)

Table format:

Rank	ID	Severity	Domains	File:Line	Description	Effort
1	COMP-001	S0	3	auth.ts:45	Missing auth check	E1

Cross-Domain Insights

Files appearing in 4+ audits needing comprehensive refactor
Security + Performance overlaps
Documentation gaps aligned with code complexity hotspots

Full Findings (Deduplicated)

Complete table grouped by severity, with links to original audit reports.

Appendix

Links to individual audit reports
Baseline metrics snapshot
False positives excluded (count)

MASTER_DEBT Deduplication (MANDATORY — before Interactive Review)

Do NOT present findings for review until they have been cross-referenced against MASTER_DEBT.jsonl. Skipping this step causes duplicate TDMS intake and inflated debt counts.

Process

Read docs/technical-debt/MASTER_DEBT.jsonl (all entries)
For each aggregated finding, search MASTER_DEBT by:
- Same file path (exact or substring match)
- Similar title/description (semantic overlap)
- Same root cause (e.g., "App Check disabled" in different wording)
Classify each finding as:
- Already Tracked: Confident match exists in MASTER_DEBT → skip intake
- New Finding: No matching DEBT entry → proceed to interactive review
- Possibly Related: Partial overlap → flag for manual review
Write report to ${AUDIT_DIR}/DEDUP_VS_MASTER_DEBT.md

Output Format

# Audit vs MASTER_DEBT Deduplication Report

## Already Tracked (skip intake)

| COMP ID | Matching DEBT ID(s) | DEBT Title | DEBT Status | Notes |

## New Findings (proceed to intake)

| COMP ID | Severity | Description |

## Possibly Related (manual review needed)

| COMP ID | Possible DEBT Match | Similarity | Notes |

Interactive Review Scope

Only present New Findings and Possibly Related items in the Interactive Review below. Already Tracked items are skipped entirely — they already exist in TDMS.

Interactive Review (MANDATORY — before TDMS intake)

Do NOT ingest findings into TDMS until the user has reviewed them.

Presentation Format

Present findings in batches of 3-5 items, grouped by severity (S0 first). Each item shows:

### DEBT-XXXX: [Title]

**Severity:** S* | **Effort:** E* | **Confidence:** \_% **Current:** [What
exists now] **Suggested Fix:** [Concrete remediation] **Acceptance Tests:** [How
to verify] **Counter-argument:** [Why NOT to do this] **Recommendation:**
ACCEPT/DECLINE/DEFER -- [Reasoning]

Wait for user decisions on each batch before presenting the next.

Decision Tracking (Compaction-Safe)

Create ${AUDIT_DIR}/REVIEW_DECISIONS.md after the first batch. Update after each batch. This file survives context compaction.

Processing Decisions

DECLINED: remove from findings before TDMS intake
DEFERRED: keep in TDMS as NEW status for future planning
ACCEPTED: proceed to TDMS intake

Post-Audit (MANDATORY)

1. Update AUDIT_TRACKER.md

Add an entry to each of the 9 category tables in docs/audits/AUDIT_TRACKER.md:

Date	Session	Commits Covered	Files Covered	Findings	Reset Threshold
{TODAY}	Comprehensive	Full codebase	All	Session #{N} - [report link]	all

2. Reset Audit Triggers (Automated)

node scripts/reset-audit-triggers.js --type=comprehensive --apply

Verify with npm run review:check (should show no triggers).

Triage & Roadmap Integration (MANDATORY)

After TDMS intake, triage new items into the roadmap with priority scoring and track assignment.

Details: See reference/TRIAGE_GUIDE.md for priority scoring formula, track assignment matrix, and consistency checks.

Context Recovery

If context compacts mid-audit, resume from last completed checkpoint.

Details: See reference/RECOVERY_PROCEDURES.md for recovery matrix, resume commands, and error handling procedures.

Completion

Display Final Summary:

COMPREHENSIVE AUDIT COMPLETE

Results Summary:
   142 raw findings -> 97 unique (45 merged)
   S0 Critical: 3
   S1 High: 24
   S2 Medium: 42
   S3 Low: 28

Cross-Domain Insights:
   8 files need comprehensive refactor (4+ audits)
   12 security/performance overlaps
   5 documentation gaps in complex areas

Full Report:
   docs/audits/comprehensive/audit-YYYY-MM-DD/COMPREHENSIVE_AUDIT_REPORT.md

Recommended Next Steps:
   1. Review top 20 priority findings
   2. Create GitHub issues for S0/S1
   3. Plan refactor for hotspot files

Usage Examples

Quarterly Health Check / Pre-Release / After Major Refactor:

/audit-comprehensive

Focused Audit (Not Comprehensive):

Use individual skills instead:

/audit-security   (25 min - when you only need security review)
/audit-code       (30 min - when you only need code quality)

Notes

Staged Execution: 4 stages (4+3+2+1 agents) respects CLAUDE.md max 4 concurrent limit
Time Estimate: ~65 minutes (vs 250min sequential = 65% savings)
S0/S1 Escalation: Security findings checked after Stage 1 before proceeding
Checkpoints: Each stage verifies outputs exist and are non-empty
Context Recovery: Can resume from any checkpoint after context compaction
Output Consistency: All audits use same severity (S0-S3) and effort (E0-E3) scales

Future Enhancements

Incremental Audits: Only re-run audits for changed domains
Custom Audit Subset: --audits code,security to run subset
Confidence Scoring: Weight findings by audit confidence levels
Trend Analysis: Compare against previous comprehensive audits
Auto-Issue Creation: Create GitHub issues for S0/S1 findings automatically

Related Skills

/audit-code - Individual code quality audit
/audit-security - Individual security audit
/audit-performance - Individual performance audit
/audit-documentation - Individual documentation audit
/audit-refactoring - Individual refactoring audit
/audit-process - Individual process/automation audit
/audit-enhancements - Individual enhancements audit
/audit-ai-optimization - Individual AI optimization audit
/audit-aggregator - Standalone aggregation (if you have existing reports)
/create-audit - Wizard to scaffold new audit types

Documentation References

Before running this audit, review:

TDMS Integration (Required)

PROCEDURE.md - Full TDMS workflow
MASTER_DEBT.jsonl - Canonical debt store

Documentation Standards (Required)

JSONL_SCHEMA_STANDARD.md - Output format requirements and TDMS field mapping
DOCUMENTATION_STANDARDS.md - 5-tier doc hierarchy

Version History

Version	Date	Description
3.2	2026-02-22	Add mandatory MASTER_DEBT dedup step before interactive review
3.1	2026-02-14	Extract reference docs: wave details, recovery, triage guide
3.0	2026-02-14	9-domain coverage: add enhancements + ai-optimization as Stage 2.5
2.1	2026-02-03	Added Triage & Roadmap Integration section with priority scoring formula
2.0	2026-02-02	Staged execution (4+2+1), S0/S1 escalation, checkpoints, context recovery
1.0	2026-01-28	Initial version - flat parallel execution of all 6 audits

Name	audit-comprehensive
Description	Run all 7 domain audits in staged waves and aggregate results