hook-ecosystem-audit

name	hook-ecosystem-audit
description	Comprehensive diagnostic of the hook ecosystem — 20 categories across 6 domains with composite health scoring, trend tracking, patch suggestions, and interactive finding-by-finding walkthrough. Covers Claude Code hooks, pre-commit pipeline, AND CI/CD pipeline health.

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

Hook Ecosystem Audit

Deep diagnostic of the entire hook ecosystem — Claude Code hooks (.claude/hooks/), shared libraries, pre-commit pipeline (.husky/pre-commit), and state management. Produces per-category scores, a composite health grade (A-F), trend tracking across runs, and an interactive walkthrough with patch suggestions.

Invocation: /hook-ecosystem-audit

Critical Rules (MUST follow)

1. CHECK for saved progress first (MUST) — resume from .claude/tmp/hook-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. If no saved progress, run the audit script before anything else.
3. ALWAYS display the dashboard (MUST) — show to user before walkthrough.
4. Use conversational Q&A for decisions (MUST) — present findings in batches, collect decisions via 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. 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 /hook-ecosystem-audit
• After adding, removing, or modifying hooks in .claude/hooks/
• After changes to .husky/pre-commit or .claude/settings.json
• After hook test failures are observed

When NOT to Use

• Auditing PR workflow state — use /pr-ecosystem-audit
• Auditing session lifecycle — use /session-ecosystem-audit
• Auditing all ecosystems at once — use /comprehensive-ecosystem-audit
• Quick hook structural check — use npm run hooks:test
• Creating or modifying a hook — direct editing (no skill needed)

Routing Guide

Concern	Audit
Hook internals, pre-commit, CI/CD	/hook-ecosystem-audit
PR review workflow	/pr-ecosystem-audit
Session lifecycle	/session-ecosystem-audit
Technical debt management	/tdms-ecosystem-audit
Skill quality	/skill-ecosystem-audit
Documentation	/doc-ecosystem-audit
Script infrastructure	/script-ecosystem-audit
All of the above	/comprehensive-ecosystem-audit

---

Process Overview

WARM-UP    Orientation    → Effort estimate, process overview
PHASE 1    Run & Parse    → Hook tests + audit script + session log
PHASE 2    Dashboard      → Composite grade, domain breakdown
PHASE 3    Walkthrough    → Interactive finding-by-finding decisions
PHASE 4    Summary        → Decision aggregate + TDMS batch summary
PHASE 5    Process Audit  → Verify audit process was followed correctly
PHASE 6    Verification   → Re-run audit to confirm fixes worked
PHASE 7    Trend Report   → Cross-run comparison (if history exists)
PHASE 8    Closure        → Retro, invocation tracking, artifact list

---

Warm-Up (MUST)

Present before any work:

Hook Ecosystem Audit
Phases: Run script → Dashboard → Interactive walkthrough → Summary → Verification
Estimated time: 15-30 min (depends on finding count)

Done when: User confirms proceed.

---

Compaction Guard

Audits are long-running interactive workflows vulnerable to context compaction.

State File

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

See REFERENCE.md for full schema.

On Skill Start (Before Phase 1) (MUST)

1. Check if .claude/tmp/hook-audit-progress.json exists and is < 2 hours old
2. If yes: resume from saved position
   • Display the dashboard from saved data (skip re-running the audit script)
   • Show: "Resuming audit from finding {n}/{total} ({n-1} already reviewed)"
   • List prior decisions: "{n} fixed, {n} skipped, {n} deferred"
   • Continue the walkthrough from currentFindingIndex
3. If no (or stale): proceed to Phase 1 normally

After Each Decision (During Phase 3) (MUST)

After each decision, immediately save progress:

1. Update currentFindingIndex to the next finding
2. Append the decision to the decisions array
3. If "Fix Now" was chosen, append to fixesApplied
4. Write the updated JSON to .claude/tmp/hook-audit-progress.json

On Audit Completion

After the closure summary, delete the progress file.

---

Dependency Constraints

This skill runs as a single-threaded sequential workflow. It does not spawn parallel agents internally. When invoked as part of /comprehensive-ecosystem-audit, it runs as one of 4 independent parallel agents in Stage 1 — no ordering required.

Orchestrator return protocol (MUST when invoked by /comprehensive-ecosystem-audit): Save JSON to .claude/tmp/ecosystem-hook-result.json and return ONLY: COMPLETE: hook grade {grade} score {score} errors {N} warnings {N} info {N}

Batch mode: The audit script supports --batch --summary flags for non-interactive orchestrated runs.

---

Phase 1: Run & Parse (MUST)

1. Run the hook test suite (MUST):

   npm run hooks:test
   

   If tests fail, proceed with audit anyway but note test failures as additional context. The audit script reads source files, not test results.

2. Run the audit script (MUST — never generate findings without data):

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

3. Parse the v2 JSON output from stdout (progress goes to stderr).

4. Create a session decision log file (MUST):

   • Path: .claude/tmp/hook-audit-session-{YYYY-MM-DD-HHMM}.jsonl
   • Schema per line: {"findingIndex","category","severity","message","decision","note","timestamp"}

5. Save initial progress state to .claude/tmp/hook-audit-progress.json.

Done when: Script output parsed, session log created, progress state saved.

---

Phase 2: Dashboard Overview (MUST)

Present the dashboard to user (MUST — Critical Rule 3).

See REFERENCE.md for the full dashboard template.

Present compact header with composite grade and domain breakdown table. Then:

Zero findings: If no findings, display dashboard with all-green scores and skip to Phase 7 (Trend Report): "Clean audit — no findings. Score: {grade} ({score}/100)."

With findings: "Found N findings to review. Walking through each one (impact-weighted)..."

Done when: Dashboard displayed to user.

---

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

Sort all findings by impactScore descending (highest impact first).

Finding Presentation (Deep-Plan Q&A Format — MUST)

For each finding, present a context card with progress header, then use the deep-plan Q&A format:

━━━ Finding {n}/{total} ({pct}% complete — {fixed} fixed, {deferred} deferred, {skipped} skipped) ━━━
{SEVERITY}  |  {domainLabel}: {categoryLabel}  |  Impact: {impactScore}/100

{message}

Evidence:
  {details}

Then present the finding using structured Q&A format:

• Description: What the finding means, with context and investigation (read the actual code before presenting — verify the finding is real)
• Options: Numbered list with pros/cons for each option
• Recommendation: Which option and why

If patchable: true, also show patch preview inline (SHOULD).

Decision Collection (Conversational Q&A — MUST)

Present findings and collect decisions via conversation. NEVER use AskUserQuestion.

ERROR findings — options: Fix Now, Defer (creates DEBT entry), or Skip with documented false-positive justification

WARNING findings — options: Fix Now, Defer, Skip

INFO findings — options: Acknowledge, Defer

To revise a previous decision, note it during any later finding and it will be captured in the session log.

Batch Shortcuts (SHOULD)

After 3+ INFO findings: offer "N more INFO findings remaining. Review each, or acknowledge all?"

After 3+ WARNING findings with no patches: offer similar batch option.

ERRORs are ALWAYS presented individually.

Scope Explosion Guard (MUST)

If total findings > 30: "30+ findings detected. Options: review all, errors-only (with summary of rest), or top-20 by impact?"

Delegation Protocol (MUST)

If user says "you decide" or similar: accept all available patches, defer findings without patches, log each as delegated-accept. Show summary of delegated decisions.

Handling Decisions

Fix Now: Apply patch if available, else provide guidance. Log to session file. Create TDMS entries one-by-one during walkthrough (MUST — prevents loss on compaction).

Defer: Create DEBT entry via /add-debt with severity S1 (errors) or S2 (warnings), category engineering-productivity, source_id review:hook-ecosystem-audit-{date}. Log to session file.

Skip: Acknowledge without tracking. Log to session file.

Post-Walkthrough Contradiction Check (SHOULD)

After all decisions, scan for contradictions (e.g., fixing a hook that a skipped finding depends on). Present any conflicts for resolution.

MUST save progress after every decision (Critical Rule 5).

Done when: All findings reviewed (or batch-acknowledged).

---

Phase 4: Summary & Actions (MUST)

See REFERENCE.md for the full summary template.

Present the summary including decisions breakdown, patches applied, top 3 impact areas, next steps, and TDMS batch summary listing all DEBT entries created.

Write summary to .claude/tmp/hook-audit-report-{YYYY-MM-DD}.md (MUST).

Done when: Summary displayed and persisted to file.

---

Phase 5: Process Self-Audit (MUST)

Verify this audit's own process was followed correctly:

• Script was run before generating findings (Critical Rule 2)
• Dashboard was displayed before walkthrough (Critical Rule 3)
• Conversational Q&A used, not AskUserQuestion (Critical Rule 4)
• Progress saved after every decision (Critical Rule 5)
• All ERROR findings addressed (fixed, deferred, or skipped with documented false-positive justification)
• TDMS entries created for all deferred findings
• __tests__/ suite passes (run: node --test .claude/skills/hook-ecosystem-audit/scripts/__tests__/*.test.js)

Present: "Process self-audit: N/N checks passed." Fix any failures before proceeding.

Gate Effectiveness Review (L6 — SHOULD)

For each pre-commit and pre-push gate, check:

1. Override frequency: Read .claude/state/override-log.jsonl — if a gate was overridden >50% of the time in the last 30 days, flag it as ineffective.
2. False positive rate: If a gate's warnings are repeatedly pre-existing debt (not new violations), it may need baseline support.
3. Catch rate: Did the gate ever block a real problem? If no evidence in override log or warning log of it catching issues, consider removing it.

Present gates with effectiveness scores: {gate}: {override%} override rate, {effectiveness} rating (effective/questionable/ineffective).

Coverage Cross-Check (Side Note — SHOULD)

Verify these mini-audit categories are covered by audit checkers. Flag any that lack automated detection:

• Override audit trail (C1) — D5 state integration
• Warning aggregation (C2) — D5 state integration
• Learnings/improvement loop (C3) — manual review only
• Pre-existing debt handling (C4) — D3 pre-commit pipeline
• Cross-system integration (C5) — manual review only
• Gate effectiveness (C7) — Gate Effectiveness Review above
• Trigger system (C9) — D4 functional correctness

Done when: All process checks pass.

---

Phase 6: Verification Re-run (SHOULD)

Re-run the audit to verify fixes improved the score:

1. Run npm run hooks:test
2. Run the audit script again
3. Compare new vs Phase 2 score

See REFERENCE.md for the verification template.

If score improved, append to trend history. If score did not improve, investigate — fixes may have introduced new findings.

Done when: Verification score compared and recorded.

---

Phase 7: Trend Report (SHOULD — skip if no history)

Trend history: .claude/state/hook-ecosystem-audit-history.jsonl (one JSONL entry per run, written by the audit script automatically).

If no previous entries exist: "First audit run — no trend data available." Skip to Phase 8.

See REFERENCE.md for the trend report template.

Done when: Trend displayed (or skipped with note).

---

Phase 8: Closure (MUST)

1. Auto-learnings (MUST): Generate 2-3 data-driven insights from audit results (top regressing category, most-fixed category, recurring issues). Save to history entry learnings field.

2. Optional user feedback (SHOULD): "Any additional observations?" Accept empty / "none" to proceed. If provided, save to process_feedback field.

3. Invocation tracking (MUST):

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

4. Closure signal (MUST):

   Audit complete. Artifacts:
     - Report: .claude/tmp/hook-audit-report-{date}.md
     - Decision log: .claude/tmp/hook-audit-session-{date}.jsonl
     - Trend entry: .claude/state/hook-ecosystem-audit-history.jsonl
   

5. Cleanup (SHOULD): Delete .claude/tmp/hook-audit-progress.json. On session-end, delete any .claude/tmp/hook-audit-* files older than 2 hours.

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 tracked, closure signal shown.

---

Guard Rails

• Zero findings: Skip walkthrough, go to Trend Report (Phase 7)
• Scope explosion: >30 findings → offer filtered review
• Disengagement: If user says "pause" or "stop": save progress, show resume instructions (/hook-ecosystem-audit auto-resumes), list decisions, exit
• Script failure: If audit script crashes or returns malformed JSON, report error and suggest npm run hooks:test for basic diagnostics
• Contradiction: Post-walkthrough scan for conflicting decisions

See REFERENCE.md for category reference, benchmarks, data sources, architecture diagram, and checker development guide.

---

Version History

Version	Date	Description
2.0	2026-03-08	Skill audit rewrite: 34 decisions, REFERENCE extraction
1.2	2026-02-24	Add D6: CI/CD Pipeline Health (3 categories)
1.1	2026-02-24	Add compaction guard for progress persistence
1.0	2026-02-23	Initial implementation