Defame1297
93d3263f8c
SKILL.md tells a dispatching agent to read the matching reference file "and no other". The retrofit moved the `pre-commit clean` confirmation gate out of the always-loaded body into references/clean.md, but references/failure-patterns.md — loaded by the diagnosis route, not the clean route — prescribes `pre-commit clean` with no gate at all. So "why is this hook failing" could wipe the machine-wide cache at ~/.cache/pre-commit for every repo without asking. The gate returns to the body, where every branch loads it, and is restated at the point of use in failure-patterns.md. It is its own section rather than a Gotchas bullet because folding it in pushed the Gotchas ratio to 41%, whose only suggested remedy is moving it back to references/ — the move that caused this. The fixer-hook rule had the same shape: reachable only behind "if the cause is not obvious from the output", which is false precisely when pre-commit prints `- files were modified by this hook`. The fix (`git add -u && git commit`) and the prohibition on `pre-commit install -f` are now unconditional, and the two weakened pointers that stranded them are restored. Found by an independent review of this branch. Refs #99
3.9 KiB
3.9 KiB
name, description, compatibility, metadata, allowed-tools
| name | description | compatibility | metadata | allowed-tools | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| pc-run | Use when the user wants to run pre-commit hooks, wire them into git, bump hook revs, maintain the cache, or diagnose why a hook fails or never fires. Not creating or editing the pre-commit config -> `pc-author`. | Requires pre-commit installed and available on PATH. |
|
Bash Read |
Gotchas
- The
SKIPenv var takes exact hookidvalues, comma-separated with no spaces:SKIP=check-yaml,gitleaks git commit -m "msg". A space after a comma silently skips nothing instead of erroring. - Never bypass a failing hook with
git commit --no-verify(or-n). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead. - files were modified by this hookis not a bug. A fixer hook (trailing-whitespace,end-of-file-fixer,pretty-format-json --autofix) rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. The fix is to re-stage and re-run the same commit:git add -u && git commit. Do NOT reach forpre-commit install -fhere — that flag overwrites hook files in.git/hooks/and has nothing to do with re-staging.
Gate — pre-commit clean
Confirm with the user before running pre-commit clean, on every path that reaches it — including when it turns up as the fix for a stale or broken environment. It wipes the whole cache at ~/.cache/pre-commit, which is machine-wide and shared by every repo on the box, forcing every hook environment to be re-downloaded.
"This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
pre-commit gc drops only unused environments and needs no confirmation — prefer it when the goal is just to reclaim disk.
Route
Determine intent from the user's request, then execute the matching operation. Where the matching row names a references/ file, read that one file and no other — each flow file is self-contained.
| User intent | Operation |
|---|---|
| "run", "check", "verify", "test hooks" | pre-commit run --all-files (default) |
| "staged", "simulate commit" | pre-commit run (staged files only) |
| "CI", "changed files only", "diff range" | pre-commit run --from-ref <base> --to-ref <head> — prefer this over --all-files on large repos |
| "install", "set up hooks", "wire into git" | pre-commit install — read references/install.md |
| "pre-create environments", "warm cache" | pre-commit install-hooks — builds every hook environment without running a hook |
| "remove hooks", "uninstall", "tear down" | pre-commit uninstall — removes pre-commit from .git/hooks/ |
| "autoupdate", "update versions", "bump revs" | pre-commit autoupdate — read references/autoupdate.md |
| "gc", "garbage collect" | pre-commit gc — drops unused cached environments only, safe at any time |
| "clean", "wipe cache", "rebuild from scratch" | pre-commit clean — read references/clean.md |
| "hooks aren't running", "hook never fires", "why did a hook fail", a hook failure whose cause is unclear | Diagnose — read references/failure-patterns.md |
If the intent is ambiguous, default to pre-commit run --all-files.
Run
Default to pre-commit run --all-files; never silently narrow to staged files. Run pre-commit run (staged only) or pre-commit run <hook-id> (one named hook) when the user asks for it.
When hooks fail:
- Name the hook and the specific cause. Be concrete — "gitleaks blocked
config.json(high-entropy string on line 12)", not "gitleaks failed". - Suggest one concrete next step. Common causes and their concrete fixes are in
references/failure-patterns.md— read it whenever the output does not already name the fix. - Do not auto-fix code files, and do not edit
.pre-commit-config.yaml— those belong to the user or topc-author.