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
• User attempts /repo-analysis on the home repo -- repo-analysis will warn and

offer to redirect here (home repo guard)

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
• When analyzing an external repo -- use /repo-analysis instead

Overview

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

1. Code Quality (audit-code) - Code hygiene, types, framework patterns
2. Security (audit-security) - Auth, input validation, OWASP compliance
3. Performance (audit-performance) - Load times, queries, caching
4. Documentation (audit-documentation) - README, API docs, architecture
5. Refactoring (audit-refactoring) - Technical debt, complexity, DRY
6. Process/Automation (audit-process) - CI/CD, testing, workflows
7. Engineering Productivity (audit-engineering-productivity) - DX,

debugging, offline support

1. Enhancements (audit-enhancements) - Feature gaps, UX improvements
2. AI Optimization (audit-ai-optimization) - Token waste, skill overlap,

hook latency

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

Orchestration Mode Selection

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

Agent Teams Mode (Preferred when available)

Requires: CLAUDECODEEXPERIMENTALAGENTTEAMS=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:

1. Lead creates shared task list with all 9 audit tasks
2. Spawn 4 teammates (grouped by related domains)
3. Teammates claim and execute audit tasks, messaging lead on S0/S1 findings
4. Teammates message peers when they find cross-cutting issues
5. Lead monitors progress, collects results as teammates complete
6. Lead performs aggregation and deduplication directly
7. 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/WAVEDETAILS.md](reference/WAVEDETAILS.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 COMPREHENSIVEAUDITREPORT.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:

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

1. Read docs/technical-debt/MASTER_DEBT.jsonl (all entries)
2. 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)

1. 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

1. Write report to ${AUDITDIR}/DEDUPVSMASTERDEBT.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 ${AUDITDIR}/REVIEWDECISIONS.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:

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/TRIAGEGUIDE.md](reference/TRIAGEGUIDE.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/RECOVERYPROCEDURES.md](reference/RECOVERYPROCEDURES.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](../../../docs/technical-debt/PROCEDURE.md) - Full TDMS workflow
• [MASTERDEBT.jsonl](../../../docs/technical-debt/MASTERDEBT.jsonl) -

Canonical debt store

Documentation Standards (Required)

• [JSONLSCHEMASTANDARD.md](../../../docs/templates/JSONLSCHEMASTANDARD.md) -

Output format requirements and TDMS field mapping

• [DOCUMENTATIONSTANDARDS.md](../../../docs/DOCUMENTATIONSTANDARDS.md) -

5-tier doc hierarchy

Version History