health-ecosystem-audit

name	health-ecosystem-audit
description	Comprehensive diagnostic of the health monitoring ecosystem — 26 categories across 6 domains with composite health scoring, trend tracking, live test execution, patch suggestions, and interactive finding-by-finding walkthrough.

Document Version: 1.0 Last Updated: 2026-03-10 Status: ACTIVE

Health Ecosystem Audit

Deep diagnostic of the health monitoring system — scripts/health/ checkers, scoring pipeline, data persistence, consumer integration, test coverage, and mid-session alert system. Produces per-category scores, a composite health grade (A-F), trend tracking, live test execution, and an interactive walkthrough with patch suggestions.

Invocation: /health-ecosystem-audit

Critical Rules (MUST follow)

1. CHECK for saved progress first (MUST) — resume from .claude/tmp/health-audit-progress.json if it exists and is < 2 hours old.
2. ALWAYS run the script first (MUST) — never generate findings without data.
3. ALWAYS display the dashboard (MUST) — show to user before walkthrough.
4. Use conversational Q&A for decisions (MUST) — NEVER use AskUserQuestion.
5. SAVE progress after every decision (MUST) — write updated state immediately.
6. Show patch suggestions inline (SHOULD) — with each patchable finding.
7. Create TDMS entries (MUST) — for deferred findings via /add-debt.
8. Save decisions (MUST) — to session log for audit trail.

---

When to Use

• User explicitly invokes /health-ecosystem-audit
• After modifying scripts/health/ checkers, lib, or scoring
• After changes to data/ecosystem-v2/ JSONL schemas
• After health check test failures are observed
• After modifying mid-session alert system

When NOT to Use

• Auditing hook infrastructure — use /hook-ecosystem-audit
• Auditing PR workflow — use /pr-ecosystem-audit
• Quick health check — use node scripts/health/run-health-check.js
• Interactive health dashboard with triage — use /ecosystem-health
• Running all ecosystem audits — use /comprehensive-ecosystem-audit

Routing Guide

Concern	Use
Health monitoring system audit	/health-ecosystem-audit
Interactive health dashboard	/ecosystem-health
Hook internals, pre-commit	/hook-ecosystem-audit
PR review workflow	/pr-ecosystem-audit
Session lifecycle	/session-ecosystem-audit
Technical debt management	/tdms-ecosystem-audit
All of the above	/comprehensive-ecosystem-audit

---

Process Overview

WARM-UP    Orientation     -> Effort estimate, process overview
PHASE 1a   Run & Parse     -> Audit script + session log
PHASE 1b   Live Tests      -> npm test execution (D5) [skippable]
PHASE 2    Dashboard       -> Composite grade, domain breakdown (worst first)
PHASE 3    Walkthrough     -> Interactive finding-by-finding decisions
PHASE 4    Summary         -> Decision aggregate + TDMS batch summary
PHASE 5    Process Audit   -> Verify process + run __tests__/ suite
PHASE 6    Verification    -> Re-run audit to confirm fixes
PHASE 7    Trend Report    -> Cross-run comparison
PHASE 8    Closure         -> Retro, invocation tracking, artifact list

---

Warm-Up (MUST)

Health Ecosystem Audit
Phases: Run script -> Live tests -> Dashboard -> Walkthrough -> Summary
Estimated time: 15-30 min (depends on finding count + live test time)
Flags: --skip-live-tests available for faster structural-only runs

Done when: User confirms proceed.

---

Compaction Guard

Path: .claude/tmp/health-audit-progress.json

See REFERENCE.md for full schema.

On Skill Start (MUST)

1. Check if progress file exists and is < 2 hours old
2. If yes: resume — display dashboard from saved data, skip re-running
3. If no: proceed to Phase 1a normally

After Each Decision (MUST)

Update currentFindingIndex, append decision, write progress file.

---

Dependency Constraints

Single-threaded sequential workflow. When invoked by /comprehensive-ecosystem-audit, runs as independent parallel agent in Stage 1 with --skip-live-tests flag (D#49).

Orchestrator return protocol: Save JSON to .claude/tmp/ecosystem-health-result.json and return ONLY: COMPLETE: health grade {grade} score {score} errors {N} warnings {N} info {N}

---

Phase 1a: Run & Parse (MUST)

1. Run the audit script (MUST):

   node .claude/skills/health-ecosystem-audit/scripts/run-health-ecosystem-audit.js --skip-live-tests
   

2. Parse v2 JSON output from stdout.

3. Create session log: .claude/tmp/health-audit-session-{YYYY-MM-DD-HHMM}.jsonl

4. Save initial progress state.

Done when: Script output parsed, session log created.

---

Phase 1b: Live Test Execution (D#34)

Unless --skip-live-tests was requested:

1. Run npm test (full suite) — output captured and parsed
2. Parse results: total, pass, fail counts per test area
3. Merge live test findings into Phase 1a results
4. D5 scores updated with live data

Done when: Live test results merged, or skipped with note.

---

Phase 2: Dashboard Overview (MUST)

Present dashboard (D#44: markdown table + sparkline trend indicators).

See REFERENCE.md for full dashboard template.

Domains sorted by score ascending (D#35: worst first).

Zero findings: Skip to Phase 7. With findings: Begin walkthrough.

---

Phase 3: Finding-by-Finding Walkthrough (MUST)

Sort findings by impactScore descending. Present using deep-plan Q&A format (D#36): read file, show context, generate patch, preview, apply on approval.

Batch Shortcuts (D#37)

After 3+ INFO/WARNING findings: offer batch acknowledgment. ERRORs always individual.

Decision Options

• ERROR: Fix Now, Defer (DEBT entry), Skip (with justification)
• WARNING: Fix Now, Defer, Skip
• INFO: Acknowledge, Defer

Test Failure Triage (D#30)

Test failures from D5: Fix Now / Defer / Skip with investigation.

Scope Explosion Guard

30 findings: offer filtered review options.

MUST save progress after every decision.

---

Phase 4: Summary & Actions (MUST)

See REFERENCE.md for summary template.

Write report to .claude/tmp/health-audit-report-{YYYY-MM-DD}.md.

---

Phase 5: Process Self-Audit (MUST)

Verify audit process AND run __tests__/ suite:

• Script was run before generating findings
• Dashboard displayed before walkthrough
• Conversational Q&A used (not AskUserQuestion)
• Progress saved after every decision
• All ERROR findings addressed
• TDMS entries created for deferred findings
• __tests__/ suite passes (run: node --test .claude/skills/health-ecosystem-audit/scripts/__tests__/*.test.js)

---

Phase 6: Verification Re-run (SHOULD)

Re-run audit to verify fixes improved score.

See REFERENCE.md for verification template.

---

Phase 7: Trend Report (SHOULD)

History: .claude/state/health-ecosystem-audit-history.jsonl

See REFERENCE.md for trend template.

---

Phase 8: Closure (MUST)

1. Auto-learnings (MUST): 2-3 data-driven insights
2. History record (MUST): Append session record to .claude/state/health-ecosystem-audit-history.jsonl with {timestamp, grade, score, testPassRate, unresolvedFindings}. This file is consumed by /alerts for the Test Health category.
3. Invocation tracking (MUST):

   cd scripts/reviews && npx tsx write-invocation.ts --data '{"skill":"health-ecosystem-audit","type":"skill","success":true,"schema_version":1,"completeness":"stub","origin":{"type":"manual"},"context":{"score":SCORE,"grade":"GRADE"}}'
   

4. Closure signal (MUST): List all artifacts
5. Cleanup (SHOULD): Delete progress file

---

Guard Rails

• Zero findings: Skip walkthrough, go to Trend Report
• Scope explosion: >30 findings -> offer filtered review
• Script failure: Report error, suggest node scripts/health/run-health-check.js
• Disengagement: Save progress, show resume instructions

See REFERENCE.md for category reference, benchmarks, schemas.

---

Version History

Version	Date	Description
1.0	2026-03-10	Initial implementation (D#1-52)