Document Version: 2.0 Last Updated: 2026-03-08 Status: ACTIVE

Script Ecosystem Audit

Deep diagnostic of scripts/**/*.js infrastructure — shared libraries, npm script registrations, and cross-script dependencies. Produces per-category scores, a composite health grade (A-F), trend tracking across runs, and an interactive walkthrough with patch suggestions.

Scope: scripts/**/*.js only. Skill-local scripts (.claude/skills/*/scripts/) are owned by /skill-ecosystem-audit.

Invocation: /script-ecosystem-audit or /script-ecosystem-audit --summary

Routing Guide

When to Use

• User explicitly invokes /script-ecosystem-audit
• Before a major script refactor or reorganization
• After adding 5+ new scripts to the scripts/ directory
• As part of /comprehensive-ecosystem-audit (called automatically)

When NOT to Use

• Auditing hook internals — use /hook-ecosystem-audit
• Auditing individual skill quality — use /skill-audit
• General code review — use /audit-code
• Quick structural check of skills — use npm run skills:validate

CRITICAL RULES (MUST — Read First)

1. CHECK for saved progress first (MUST) — resume from .claude/tmp/script-audit-progress.json if it exists and is < 2 hours old. Never re-present findings that were already decided.
2. ALWAYS run the script first (MUST) — never generate findings without data
3. ALWAYS display the dashboard (MUST) before starting the walkthrough
4. Present findings via conversational Q&A (MUST) — collect decisions through normal conversation. NEVER use AskUserQuestion.
5. SAVE progress after every decision (MUST) — write updated state to progress file immediately
6. Show patch suggestions inline (SHOULD) with each patchable finding
7. Include a recommendation with rationale (MUST) per finding
8. Create TDMS entries (SHOULD) for deferred findings via /add-debt

Arguments & Modes

Compaction Guard

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

Read REFERENCE.md for progress file schema.

On Skill Start (MUST — Before Phase 1)

1. Check if progress file exists and is < 2 hours old
2. If yes: resume — display dashboard from saved data, show "Resuming from finding {n}/{total} ({n-1} reviewed)", continue walkthrough
3. If no (or stale): proceed to Phase 1

After Each Decision (MUST — During Phase 3)

Update currentFindingIndex, append decision, write progress file immediately.

On Completion

Delete progress file. Append results to history JSONL.

Phase 1: Run & Parse

1. Run the audit script:

   node .claude/skills/script-ecosystem-audit/scripts/run-script-ecosystem-audit.js

2. If script fails (MUST handle): display error, suggest checking node --version and module dependencies. Do NOT proceed with empty data.
3. Parse v2 JSON output from stdout (progress goes to stderr)
4. Create session log: .claude/tmp/script-audit-session-{YYYY-MM-DD-HHMM}.jsonl
5. Save initial progress state with currentFindingIndex: 0

Read REFERENCE.md for v2 JSON output schema and session log JSONL schema.

Done when: Progress file written with score, grade, and findings data.

Phase 2: Dashboard Overview

MUST display the dashboard before starting walkthrough.

Read REFERENCE.md for dashboard template.

Present compact header with composite grade, domain breakdown, category scores.

If 0 findings (MUST handle): display score, skip Phase 3, go directly to Phase 4. "No findings — script infrastructure is clean."

After dashboard, show effort estimate: "Found N findings. Estimated review time: ~{N×0.3} min full, ~{top20×0.3} min top-20 only."

If >50 findings (MUST): "50+ findings detected. Review top 20 by impact, then batch-decide the rest? [Y/review all]"

Done when: Dashboard displayed, user confirms walkthrough approach.

Phase 3: Finding-by-Finding Walkthrough

MUST use conversational Q&A — NOT AskUserQuestion. MUST save progress after every decision.

Sort findings by impactScore descending. Present each with a context card:

Read REFERENCE.md for finding card template.

Each finding MUST include a recommended action with brief rationale.

Decision Options

ERROR findings: Fix Now | Defer (→ DEBT entry) WARNING findings: Fix Now | Defer | Skip INFO findings: Acknowledge | Defer

Decision Handling

• Fix Now: Apply patch if available, provide guidance if not
• Defer: Create DEBT entry via /add-debt (S1 for errors, S2 for warnings)
• Skip/Acknowledge: Log to session file

After Each Decision

Show running tally: "Progress: {n}/{total} | Fixed: {f} | Deferred: {d} | Skipped: {s}"

Delegation Protocol (MUST support)

• "you decide" → accept all recommendations
• "skip remaining INFO" → batch-skip all remaining INFO findings
• "fix all patchable" → apply all remaining patches without individual review
• "defer the rest" → defer all remaining findings as DEBT entries

Batch Management (MUST for >20 findings after top-20)

After reviewing top 20, present remaining by severity: "N remaining: {e} errors, {w} warnings, {i} info. Review all / Warnings+ only / Skip to summary?"

Done when: All findings decided or batch-resolved.

Phase 4: Summary, Trend & Actions

Present unified summary with trend data (if previous runs exist):

Read REFERENCE.md for summary template.

Include:

• Decision breakdown (fixed/deferred/skipped counts)
• Patches applied count
• Top 3 impact areas
• Trend data (SHOULD) — if history JSONL has entries, show direction + delta per category. Flag categories poor across 2+ consecutive runs: "{category} has been {rating} for {N} consecutive runs."
• Artifact list (MUST): session log path, DEBT entries created, files patched, history updated

Done when: Summary presented to user.

Phase 5: Self-Audit Verification

Run __tests__/ suite to confirm audit integrity:

node --test .claude/skills/script-ecosystem-audit/scripts/__tests__/*.test.js

Re-run the audit script and compare:

node .claude/skills/script-ecosystem-audit/scripts/run-script-ecosystem-audit.js

Read REFERENCE.md for self-audit template.

Present before/after comparison. If score didn't improve, investigate why.

Done when: Before/after comparison presented.

Phase 6: Learning Loop & Closure (MUST)

1. Auto-learnings (MUST): Generate 2-3 data-driven insights from audit results. E.g., "Top regressing category: X. Most-fixed category: Y. Recurring issue: Z poor for N consecutive runs." Save to history JSONL learnings field.
2. Optional user feedback (SHOULD): "Any additional observations or patterns the checkers should learn?" Accept empty / "none" to proceed. If provided, save to history JSONL feedback field.
3. Invocation tracking (MUST):

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

4. Delete progress file (audit complete)

On next startup (MUST): If history JSONL has entries, surface previous auto-learnings and user feedback: "Previous run noted: [learnings]. User feedback: [if any]."

Done when: Learnings generated, invocation logged, progress file deleted.

Guard Rails

• Script failure: Display error + diagnostics, do not proceed with empty data
• Empty results: Skip walkthrough, show clean score
• Pause/resume: User says "pause" → save state, print progress, exit. Resume: /script-ecosystem-audit reads progress file and continues.
• Circuit breaker: >50 findings → offer top-20 review + batch
• Session log retention: Ephemeral in .claude/tmp/, not archived by /session-end. Retained for current session only.

Integration

Neighbors: /hook-ecosystem-audit (hooks), /comprehensive-ecosystem-audit (orchestrator), /skill-ecosystem-audit (skill scripts), /add-debt (TDMS)

Comprehensive audit integration: When called by /comprehensive-ecosystem-audit, the script runs with --batch --summary flags and returns JSON to stdout. The orchestrator expects: { grade, score, errors, warnings, info, patches, domains }.

Artifact Contracts:

Category checks enforce patterns from CLAUDE.md Section 5 (Critical Anti-Patterns). See CLAUDE.md for canonical definitions.

Version History