bcbeidel/check-pre-commit-config

Check Pre-Commit Config

Audit a .pre-commit-config.yaml — plus the local shell/Python scripts it invokes — for reproducibility, scope, safety, error handling, and adherence to the pre-commit framework's conventions. The rubric lives in pre-commit-config-best-practices.md.

This skill follows the check-skill pattern. Tier-1 detection is in 6 scripts emitting JSON envelopes via _common.py (20 rule_ids total). Tier-2 has 7 judgment dimensions read inline by the primary agent. Tier-3 is collision (cross-config duplication).

When to use

Also fires when the user phrases the request as:

• "check .pre-commit-config.yaml"
• "is my pre-commit config safe"
• "what's wrong with my pre-commit"

Workflow

1. Scope

Read $ARGUMENTS. Resolve to a .pre-commit-config.yaml (or .yml) at the path or repo root. Confirm scope aloud.

2. Tier-1 Deterministic Checks

Invoke 6 detection scripts:

SCRIPTS="${SKILL_DIR}/scripts"
TARGET="$ARGUMENTS"   # path to .pre-commit-config.yaml

python3 "$SCRIPTS/check_yaml_shape.py"            $TARGET   # 4 rules: config-missing, yaml-parse, repos-key, hook-shape (FAIL)
python3 "$SCRIPTS/check_rev_pinning.py"           $TARGET   # 2 rules: floating-rev (FAIL), rev-shape (WARN)
python3 "$SCRIPTS/check_hook_scope.py"            $TARGET   # 2 rules: hook-scope, pass-filenames-false (WARN)
python3 "$SCRIPTS/check_safety.py"                $TARGET   # 5 rules: network-io, destructive-git, destructive-shell, sudo, error-suppression (all FAIL)
bash    "$SCRIPTS/check_script_strictness.sh"     <referenced .sh files>   # 1 rule: shell-strictness (FAIL)
python3 "$SCRIPTS/check_hygiene.py"               $TARGET   # 6 rules: min-version, lang-version-pin, hook-id, local-hook-name, require-serial, builtin-duplication

Each script emits a JSON array of envelopes. recommended_changes is canonical — copy through verbatim.

Script-to-rules map (20 Tier-1 rule_ids):

| Script | rule_ids | Severity | |---|---|---| | check_yaml_shape.py | config-missing, yaml-parse, repos-key, hook-shape | fail | | check_rev_pinning.py | floating-rev | fail | | check_rev_pinning.py | rev-shape | warn | | check_hook_scope.py | hook-scope, pass-filenames-false | warn | | check_safety.py | network-io, destructive-git, destructive-shell, sudo, error-suppression | fail | | check_script_strictness.sh | shell-strictness | fail | | check_hygiene.py | hook-id | fail | | check_hygiene.py | min-version, lang-version-pin, local-hook-name, require-serial, builtin-duplication | warn |

Tier-2 exclusion list. Any FAIL in config-missing, yaml-parse, repos-key, hook-shape, floating-rev, any safety rule (network-io, destructive-git, destructive-shell, sudo, error-suppression), shell-strictness, or hook-id excludes the config from Tier-2.

3. Tier-2 Judgment Dimensions

For each config that passed the Tier-2 exclusion gate, evaluate against the 7 judgment rules at references/check-*.md:

| File | Dimension | Severity | |---|---|---| | check-reproducibility.md | D1 — pinned versions; deterministic across machines | warn | | check-scope-discipline.md | D2 — hooks scoped to relevant files via files/types | warn | | check-safety-posture.md | D3 — no network I/O, history rewrites, destructive ops | warn | | check-error-handling-and-messaging.md | D4 — exit codes communicate intent; messages name the failing operation | warn | | check-performance-intent.md | D5 — file-mutating hooks declare require_serial | warn | | check-developer-experience.md | D6 — names + ids developer-facing; minimum_pre_commit_version pinned | warn | | check-hook-structure.md | D7 — repo entries grouped logically; one concern per hook | warn |

Evaluator policy: see check-skill-pattern.md §Evaluator policy. Read all 7 rule files first, then evaluate the config in one LLM call.

4. Tier-3 Cross-Config Collision

Evaluate against check-collision.md. For multi-repo audits or org-wide scans, surface duplicate hook definitions / boilerplate across configs as warn. Single-config scope returns inapplicable.

5. Report

Merge findings from all 3 tiers into a unified table:

| Tier | rule_id | Location | Status | Reasoning |
|------|---------|----------|--------|-----------|

Sort: fail before warn before inapplicable; Tier-1 before Tier-2 before Tier-3 within severity. Each Recommendation: line copies through recommended_changes verbatim.

6. Opt-In Repair Loop

Ask once:

"Apply fixes? Enter y (all), n (skip), or comma-separated numbers."

For each selected finding:

• Direct edit — rev: pin, hook id/name, files/types scope, require_serial: true. Show diff; write on confirmation.
• Routed to another skill — substantial rewrites → /build:build-pre-commit-config.
• Tier-2/3 judgment — ask the user; rewrite the section; show diff; write on confirmation.

After each applied fix, re-run the relevant Tier-1 script. Terminate when the user enters n or exhausts findings.

Anti-Pattern Guards

1. Per-dimension LLM call. Collapse into one locked-rubric call per config.
2. LLM-evaluating format compliance. YAML shape, rev pinning, hook id presence — handle deterministically in Tier-1.
3. Ambiguous compliance reported as PASS. Surface as WARN (default-closed).
4. Bulk-applying fixes. Per-finding confirmation required.
5. Re-evaluating scripted rules in Tier-2. Scripts are authoritative for the 20 Tier-1 rules.
6. Suppressing the inapplicable envelope. When the cisco scanner / external tools are missing, surface inapplicable.
7. Embellishing scripts' recommended_changes. Each rule's recipe constant is canonical guidance.

Key Instructions

• Run Tier-1 first; gate LLM evaluation on structural validity.
• Present all 7 Tier-2 dimensions as a single locked-rubric call.
• Include the full config and referenced scripts verbatim in LLM evaluation.
• Recovery: read-only outside the Repair Loop.

Handoff

Chainable to: /build:build-pre-commit-config (rebuild non-compliant config from scratch).