--- name: comprehensive-ecosystem-audit description: | Orchestrates all 8 ecosystem audits in staged waves with 4-concurrent-agent limit, aggregates results into a unified health report with cross-audit insights, domain heat maps, and priority-ranked findings. supports_parallel: true fallback_available: false estimated_time_parallel: 30 min estimated_time_sequential: 90 min --- **Document Version:** 1.1 **Last Updated:** 2026-02-24 **Status:** ACTIVE # Comprehensive Ecosystem Audit Orchestrates all 8 ecosystem audits (hook, session, TDMS, PR, health, skill, doc, script) in 2 staged waves, aggregates results into a unified health report. **Invocation:** `/comprehensive-ecosystem-audit` **Output:** `COMPREHENSIVE_ECOSYSTEM_AUDIT_REPORT.md` in the project root. --- ## CRITICAL RULES 1. **CHECK for saved progress first** -- resume from `.claude/tmp/comprehensive-ecosystem-audit-progress.json` if < 2 hours old. 2. **Run audits via npm scripts / node commands**, not by reading checker code. 3. **CRITICAL RETURN PROTOCOL:** Each agent saves JSON to `.claude/tmp/ecosystem-{name}-result.json` and returns ONLY: `COMPLETE: {audit-name} grade {grade} score {score} errors {N} warnings {N} info {N}` 4. **Check completion via `wc -l`/`wc -c` on output files**, never read full output into context. 5. **Save progress after each stage** to survive context compaction. --- ## Compaction Guard State file: `.claude/tmp/comprehensive-ecosystem-audit-progress.json` Tracks stages (pending/completed), individual audit status (pending/running/completed/failed), and result summaries (grade, score, counts). | State | Resume Action | | ----------------------------- | ------------------------------------ | | No file or > 2 hours old | Start fresh | | Stage 1 partial | Re-run pending/failed Stage 1 audits | | Stage 1 done, Stage 2 pending | Run Stage 2 | | Stage 2 done, Stage 3 pending | Run Stage 3 (aggregation) | | Stage 3 done | Display final report | > **Details:** See > [reference/RECOVERY_PROCEDURES.md](reference/RECOVERY_PROCEDURES.md) --- ## Stage 1: Foundation Audits (5 parallel, D#7) **Dependencies:** All 5 agents are independent. Stage 2 depends on Stage 1. Health audit uses `--skip-live-tests` for speed during comprehensive runs (D#49). | Agent | Audit | Script | Result File | | ----- | ------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | 1 | Hook | `node .claude/skills/hook-ecosystem-audit/scripts/run-hook-ecosystem-audit.js --batch --summary` | `ecosystem-hook-result.json` | | 2 | Session | `node .claude/skills/session-ecosystem-audit/scripts/run-session-ecosystem-audit.js --batch --summary` | `ecosystem-session-result.json` | | 3 | TDMS | `node .claude/skills/tdms-ecosystem-audit/scripts/run-tdms-ecosystem-audit.js --batch --summary` | `ecosystem-tdms-result.json` | | 4 | PR | `node .claude/skills/pr-ecosystem-audit/scripts/run-pr-ecosystem-audit.js --batch --summary` | `ecosystem-pr-result.json` | | 5 | Health | `node .claude/skills/health-ecosystem-audit/scripts/run-health-ecosystem-audit.js --batch --summary --skip-live-tests` | `ecosystem-health-result.json` | After completion: verify files exist, check sizes with `wc -c`, update progress. > **Details:** See [reference/WAVE_DETAILS.md](reference/WAVE_DETAILS.md) --- ## Stage 2: Extended Audits (3 parallel) | Agent | Audit | Script | Result File | | ----- | ------ | ---------------------------------------------------------------------------------------------------- | ------------------------------ | | 6 | Skill | `node .claude/skills/skill-ecosystem-audit/scripts/run-skill-ecosystem-audit.js --batch --summary` | `ecosystem-skill-result.json` | | 7 | Doc | `node .claude/skills/doc-ecosystem-audit/scripts/run-doc-ecosystem-audit.js --batch --summary` | `ecosystem-doc-result.json` | | 8 | Script | `node .claude/skills/script-ecosystem-audit/scripts/run-script-ecosystem-audit.js --batch --summary` | `ecosystem-script-result.json` | --- ## Stage 3: Aggregation & Report Generation Sequential. Read ONLY summary sections from each result file (first 50 lines or `summary` key). ### Weighted Health Grade | Audit | Weight | Rationale | | ------- | ------ | ------------------------------ | | Hook | 14% | Core infrastructure | | Session | 9% | Session management | | TDMS | 14% | Debt tracking | | PR | 14% | Review workflow quality gate | | Health | 10% | Health monitoring system (D#7) | | Skill | 18% | Largest surface area | | Doc | 9% | Supporting infrastructure | | Script | 12% | Build/test/deploy pipeline | Formula: `overallScore = sum(score * weight) / sum(completed_weights)` Grades: A=90+, B=80+, C=70+, D=60+, F=<60. ### Cross-Audit Analysis 1. **Domain Heat Map** -- bottom 10 category scores across all audits 2. **Shared File Hotspots** -- files in findings from 3+ audits 3. **Common Pattern Violations** -- anti-patterns in multiple audits 4. **Top 20 Findings** -- top 3 from each audit, ranked by impact ### Report Output Write `COMPREHENSIVE_ECOSYSTEM_AUDIT_REPORT.md`: Executive Summary, Audit Results table, Domain Heat Map, Top 20 Priority Findings, Cross-Audit Insights (hotspots, patterns, gaps), Recommendations, Appendix (scripts, failed audits). ### Cleanup Update progress to completed, delete result files and progress file, present summary. --- ## Partial Failure Handling If audit(s) fail: mark as "failed", log error, continue with remaining. Compute weighted average using only completed audits. Note missing coverage in report. **Never block entire audit for one sub-audit failure.** --- ## When to Use - Quarterly health check - After major refactoring - Before a release - After adding new hooks/skills/scripts ## When NOT to Use - Quick single-domain check (use individual audit skills) - Debugging specific issues (use `/systematic-debugging`) - When context budget is tight (8 agent launches) ## Related Skills Individual audits: `/hook-ecosystem-audit`, `/session-ecosystem-audit`, `/tdms-ecosystem-audit`, `/pr-ecosystem-audit`, `/health-ecosystem-audit`, `/skill-ecosystem-audit`, `/doc-ecosystem-audit`, `/script-ecosystem-audit`. Also: `/audit-comprehensive` (9-domain code audit -- different scope). --- ## Version History | Version | Date | Description | | ------- | ---------- | ------------------------------------------------------ | | 1.2 | 2026-03-10 | Add health-ecosystem-audit as #8 to Stage 1 (D#7) | | 1.1 | 2026-02-24 | Trim to <500 lines: condense tables and agent prompts | | 1.0 | 2026-02-24 | Initial -- 7 audits in 2 staged waves with aggregation |