# Hook Audit

> Analyze hook effectiveness + session retro from collected metrics. Use when user asks to audit hooks, invokes `/hook-audit`, wants to identify silent/over-aggressive/under-enforced hooks, or asks for a retro / team analytics across recent sessions.

- Skill: `redpanda-data/hook-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add redpanda-data/hook-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redpanda-data/hook-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: redpanda-data (https://skillmd.com/u/redpanda-data)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redpanda-data/hook-audit

---


# Hook audit

## Step 0: Gather context

Run Bash commands before proceed:

- `ls "$(git rev-parse --show-toplevel 2>/dev/null)/.claude/hooks/"*.sh 2>/dev/null | wc -l` -- installed hook scripts
- `ls ~/.claude/hook-metrics/*.json 2>/dev/null | wc -l` -- session summaries collected
- `ls ~/.claude/hook-metrics/*.json 2>/dev/null | head -1 | xargs -I{} jq -r '.date' {}` -- earliest date
- `ls ~/.claude/hook-metrics/*.json 2>/dev/null | tail -1 | xargs -I{} jq -r '.date' {}` -- latest date

Metrics dir: `~/.claude/hook-metrics/`

## Your task

Analyze hook effectiveness across all session metrics. Read every JSON in `~/.claude/hook-metrics/`. Produce report:

### 1. Hook activity

Each hook fired >=1 across sessions:
- Total blocks, warns, denies
- Avg fires per session
- Trend: up or down over time?

### 2. Silent hooks

List hook scripts in `.claude/hooks/` with **zero entries** in any metrics file. Prune candidates -- never trigger or not wired to logging.

### 3. Over-aggressive hooks

High block counts hurt productivity:
- Blocks-per-session ratio > 3 -> flag too strict
- Same rule blocked repeat in one session -> agent retry and fail

### 4. Enforcement gaps

Cross-ref CLAUDE.md rules vs hook activity:
- Rules with hook but zero fires -> followed perfect or untested
- Rules with no hook -> advisory, no enforce

### 5. Recommendations

From data:
- **Prune**: hooks never fire (remove or merge)
- **Soften**: hooks block too much (demote to warn)
- **Harden**: warns fire often (promote to block)
- **Add**: CLAUDE.md rules with no hook enforce

### 6. Retro analytics (session flow)

Broader than hook-level. Pull from session JSONL + git log same window as metrics.

- **Sessions -> PR lag**: median time from first edit to PR open. High lag = planning thrash.
- **CI first-try pass rate**: PRs green on first CI run / total PRs. Low = hooks missed pre-commit catches.
- **Phases skipped in `/development-lifecycle`**: sessions wrote code without prior grill step (infer from session-touched-files + absence of grill markers). High skip = gate ineffective.
- **Review-round distribution**: how often hit 0/1/2/3 AI self-review rounds? Bulk at 3 = reviewer too picky or code quality trending down.
- **Human-review resolution latency**: time from human review comment -> resolved thread. High = bottleneck.
- **Worktree sprawl**: count active worktrees per repo. >4 sustained -> investigate with `/mux --list` candidates for prune.

Output per-metric: current value, 7-day trend (up/down/flat), actionable next step.

### Mode flags

`$ARGUMENTS`:
- empty / `--hooks` -> run sections 1-5 only (default).
- `--retro` -> run sections 1-6 with emphasis on section 6.
- `--all` -> all sections, no emphasis.

### Output format

Structured report. Tables where data fit. End with prioritized action list (max 5). If <5 session files, note data limited, recs preliminary.