# Hook Updater

> Research-backed hook refresh workflow for updating existing hooks with TDD checkpoints and settings.json registration validation.

- Skill: `oimiragieo/hook-updater` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/hook-updater`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/hook-updater/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/oimiragieo/hook-updater

---


# Hook Updater

## Overview

Use this skill to refresh an existing hook safely: research current best practices, compare against current implementation, generate a TDD patch backlog, apply updates, and verify ecosystem integration including settings.json registration.

## When to Use

- Reflection flags stale or malfunctioning hook behavior
- EVOLVE determines hook capability exists but quality is outdated
- User asks to audit/refresh an existing hook
- Hook exit code or stdin protocol issues detected

## The Iron Law

Never update a hook blindly. Every refresh must be evidence-backed, TDD-gated, and integration-validated.

## Workflow

### Step 0: Evaluate Current State

1. Read the hook file and understand its purpose
2. Check settings.json registration (which events, which matchers)
3. Run existing tests if they exist
4. Identify issues: wrong API pattern, missing registration, broken requires

### Step 1: Research Best Practices

1. Read `.claude/hooks/CLAUDE.md` for hook conventions
2. Review similar hooks in the same category for patterns
3. Check `.claude/rules/hooks.md` for hook rules
4. Use `Skill({ skill: 'research-synthesis' })` if external research needed

### Step 2: Generate Patch Backlog

1. List specific changes needed (TDD-style: test first, then implement)
2. Prioritize by risk: registration fixes > exit code fixes > logic improvements
3. Estimate scope: <30 lines = auto-apply, >30 lines = plan mode

### Step 3: Apply Updates

1. Write or update tests first (RED phase)
2. Apply hook changes (GREEN phase)
3. Refactor for clarity (REFACTOR phase)
4. Use `Edit` tool — never rewrite the entire file

### Step 4: Verify Integration

1. Confirm hook is registered in `.claude/settings.json` for correct events
2. Verify hook exit codes: 0=allow, 2=block, 1=error (SE-03)
3. Verify stdin JSON parsing follows the standard protocol
4. Run `pnpm lint:fix && pnpm format`
5. Run hook-specific tests

### Step 5: Record

1. Log changes via `MemoryRecord` if significant
2. Update CHANGELOG.md entry

## Domain-Specific Validation

- Hook MUST be registered in settings.json under appropriate event
- Hook MUST use stdin JSON protocol (not programmatic function exports)
- Hook MUST exit 0 (allow) or 2 (block) — never exit 1 for blocking
- Hook MUST wrap body in try/catch, exit 0 on unexpected errors (SE-03)
- Hook require() paths MUST be file-relative (../../lib/...), not CWD-relative

## Anti-Patterns

- Updating a hook without checking its settings.json registration
- Changing exit codes without understanding the 0/1/2 semantics
- Converting a stdin-protocol hook to programmatic API (or vice versa)
- Removing error handling to "simplify" the hook