---

name: pre-commit-fixer description: | Automatically fix pre-commit hook failures and retry the commit. Use when a git commit fails due to ESLint errors, pattern compliance violations, missing document headers, cross-document dependency issues, or documentation index staleness. Spawns a targeted subagent to fix each category of failure, then re-stages and re-commits. Reduces context waste from manual fix-commit-retry cycles.

<!-- prettier-ignore-start -->

Document Version: 1.1 Last Updated: 2026-02-14 Status: ACTIVE

<!-- prettier-ignore-end -->

Pre-Commit Fixer

When NOT to Use

• When the task doesn't match this skill's scope -- check related skills
• When a more specialized skill exists for the specific task

Purpose

Eliminate the context-heavy fix-commit-retry loop that happens when pre-commit hooks fail. Instead of manually reading errors, fixing files, re-staging, and re-committing (burning 500+ tokens per cycle), delegate the fix to a focused subagent that works in bounded context.

When to Use

Use this skill when git commit fails with any of these pre-commit errors:

| Error Category | Detection Pattern | | ------------------------- | ------------------------------------------------ | | ESLint failures | ESLint passed (N errors) or eslint in output | | Pattern compliance | Pattern compliance failed | | Document headers | Missing required header in output | | Cross-doc dependencies | not staged or cross-document in output | | Documentation index stale | DOCUMENTATION_INDEX.md not updated in output | | Skill validation | Skill validation failed |

Workflow

Step 1: Capture the Error

When a commit fails, capture the FULL error output. The error output contains the exact information needed for the fix.

Step 2: Classify the Failure

Read the error output and classify into one of these categories:

Category A: Auto-fixable (no subagent needed)

These can be fixed inline without spawning an agent:

1. Documentation index stale → Run npm run docs:index && git add DOCUMENTATION_INDEX.md
2. Cross-doc dependency → Stage the missing file: git add <missing-file>
3. Lint-staged formatting → Already auto-fixed by lint-staged, just re-commit

Category B: Targeted fix (spawn subagent)

These need code analysis and changes:

1. ESLint errors → Spawn debugger agent with error list and file paths
2. Pattern compliance → Spawn code-reviewer agent with violation details
3. Document headers → Add headers directly (template below)
4. Skill validation → Spawn general-purpose agent with skill file path

Step 3: Execute Fix

For Category A (inline fix):

# Documentation index
npm run docs:index && git add DOCUMENTATION_INDEX.md

# Cross-doc dependency (example)
git add .claude/COMMAND_REFERENCE.md

# Re-commit using the original message (preserved by git after hook failure)
git commit -F .git/COMMIT_EDITMSG

For Category B (subagent fix):

Spawn a focused subagent using the Task tool:

Task({
  subagent_type: "debugger",
  description: "Fix N pre-commit ESLint errors",
  prompt: "Fix these ESLint errors and stage the fixes:\n\n<paste error output>\n\nFiles to fix: <list>\n\nDo NOT create new files. Only fix the listed errors."
})

After the subagent returns, re-stage and re-commit.

Step 4: Document Header Template

For new .md files missing headers, add this block after the YAML frontmatter (if any) or at the top of the file:

<!-- prettier-ignore-start -->
**Document Version:** 1.0
**Last Updated:** YYYY-MM-DD
**Status:** ACTIVE
<!-- prettier-ignore-end -->

Step 5: Re-commit

After all fixes are applied and staged:

git add <fixed-files>
git commit -m "original commit message"

If the commit fails again, repeat from Step 1. Cap at 3 retry cycles — if it still fails after 3 attempts, report the remaining errors to the user.

Anti-Patterns

• Do NOT use SKIP_* environment variables to bypass checks unless the user explicitly requests it
• Do NOT suppress ESLint rules with // eslint-disable unless the rule is genuinely a false positive
• Do NOT add files to pathExcludeList in check-pattern-compliance.js unless they are verified false positives
• Do NOT commit partial fixes — fix ALL reported errors before re-committing

Input/Output Format

Input: The full stderr/stdout from a failed git commit command.

Output: After all fixes are applied and committed, report a structured summary:

PRE-COMMIT FIX RESULT:
  Status: SUCCESS | PARTIAL | FAILED
  Attempt: N/3
  Failures fixed:
    - [category]: [description] ([file])
  Remaining (if any):
    - [category]: [description]
  Commit: [hash] (if successful)

Expected Behavior Per Failure Type

| Failure Type | Fix Strategy | Auto-fixable? | | ---------------------- | --------------------------------------------------------------------- | ------------- | | ESLint errors | Read error list, fix each in source, re-stage | Subagent | | Pattern compliance | Read violation, apply pattern from CODE_PATTERNS.md | Subagent | | Cross-doc dependencies | git add the unstaged dependency file | Inline | | Doc index stale | npm run docs:index && git add DOCUMENTATION_INDEX.md | Inline | | Doc headers missing | Add standard header block (template in Step 4) | Inline | | Skill validation | Read error, fix SKILL.md frontmatter or structure | Subagent | | S0/S1 audit failure | Check if real or false positive; fix or set SKIP_AUDIT_VALIDATION=1 | Subagent | | Schema validation | Fix JSONL schema issues in the flagged file | Subagent |

Context Efficiency

This skill saves context by:

1. Avoiding multiple round-trips of reading error → thinking → fixing → retrying
2. Delegating ESLint/pattern fixes to bounded subagents
3. Using deterministic templates for doc headers instead of researching format
4. Capping retry cycles to prevent unbounded loops

---

Version History

| Version | Date | Description | | ------- | ---------- | ---------------------- | | 1.0 | 2026-02-25 | Initial implementation |