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