| name | hk-troubleshooting |
| description | This skill should be used when the user encounters hk hook failures including stash restoration errors, step failures, environment issues, and configuration problems. Use when pre-commit hooks fail, when hk behaves unexpectedly, or when hooks pass/fail inconsistently.
|
hk Troubleshooting
Self-Improving Debug Protocol
Follow this cycle iteratively until the issue is resolved:
1. Gather Evidence
hk config dump --json
hk config explain stash
hk config explain stash_untracked
hk validate
hk --version
hk run pre-commit --verbose
hk run pre-commit --trace
2. Common Failure Patterns
Stash Restore Failure
Symptom: fatal: path '<file>' exists on disk, but not in 'stash@{0}^1'
Root cause: stash_untracked=true (default) includes ALL untracked files in the stash.
When new files are staged but don't exist in the prior commit tree, git can't find them
for restoration.
Fix:
git config --local hk.stashUntracked false
Why this is safe: Hooks only check staged files. Untracked files don't affect hook results.
If stash is stuck: git stash drop to clear the preserved stash.
Hook Passes But Manual Run Fails
Check these in order:
- Stash behavior: Hook sees only staged files, manual sees everything
- exclude patterns: hk.pkl excludes may differ from tool config
- PATH: hk may not find mise-managed tools — check
mise = true in config
- Working directory: Hook runs from repo root, manual may not
Step Timeout
Default timeout: None (steps run until completion)
Fix: Add timeout to step definition or split into smaller steps.
Permission Denied on Hook Scripts
chmod +x .git/hooks/pre-commit
hk install
3. Nuclear Options (last resort)
git commit --no-verify -m "message"
hk uninstall && hk install
rm -rf .git/hk/
4. Report Upstream
If the issue is in hk itself:
gh issue create --repo jdx/hk --title "<title>" --body "<reproduction steps>"
