Runbook: Pre-commit Failing

Trigger

• make pre-commit-check fails.
• git commit fails because a hook failed.

Fast triage

1. Run hooks: make pre-commit-check.
2. Check which hook failed (ruff, format, mypy, hygiene hooks).
3. Fix issues, then run again; hooks may edit files for you.

Most common causes

• ruff-format changed files but they were not staged before commit.
• mypy reports type errors after schema/service edits.
• Hygiene hooks found trailing spaces/EOF/line endings.
• Merge conflict markers accidentally committed.

Recovery steps

1. Apply auto-fixes: make lint-fix, make format-fix.
2. Stage updated files: git add -A.
3. Re-run hooks: make pre-commit-check.
4. If mypy still fails, run make type-check and fix typing issues.

Special case: unstaged changes conflict

If commit output shows stash/rollback conflict:

• Stage all intended files first: git add -A.
• Run make pre-commit-check.
• Commit again.

Exit criteria

• make pre-commit-check passes.
• No auto-modified files remain unstaged.
• Commit succeeds without hook rollback.

Follow-up

• To change which hooks run or how strict they are, edit .pre-commit-config.yaml.
• If the same failure keeps happening, add a line to this runbook.

Page history