check-pre-commit-config

name	check-pre-commit-config
description	Audits a `.pre-commit-config.yaml` (and referenced local hook scripts) against 20 deterministic checks (YAML shape, `rev:` pinning, scope declarations, network-call / destructive-command / error-suppression patterns, shell-script strict mode, hook explicit-name and require-serial hygiene) plus seven judgment dimensions and a Tier-3 cross-config collision check. Use when the user wants to "audit pre-commit", "lint pre-commit", or "review my pre-commit hooks". Not for hand-rolled `.git/hooks/` — out of scope. Not for CI pipelines — route elsewhere.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
argument-hint	[path-to-repo-root-or-config-file]
user-invocable	true
references	["../../_shared/references/pre-commit-config-best-practices.md","references/check-collision.md","references/check-developer-experience.md","references/check-error-handling-and-messaging.md","references/check-hook-structure.md","references/check-performance-intent.md","references/check-reproducibility.md","references/check-safety-posture.md","references/check-scope-discipline.md"]
license	MIT

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).