---
name: audit-slop-prevention
description: Use when auditing a repository's full commit history for repeated agent-generated defects, slop, regressions, review-fix loops, weak tests, missing guards, or when designing agent instructions, fast hooks, pre-commit checks, slopgate rules, and CI merge gates that prevent recurrence.
---

# Audit Slop Prevention

Audience: AI coding agents first.

## Core rule

Mine evidence before recommending controls. Every confirmed recurring or critical defect MUST map to executable regression coverage. Record reasoning-only blind spots only when deterministic verification cannot decide correctness.

NEVER claim “full history reviewed” from sampled logs. Inventory every commit reachable by `git rev-list --all`; reconcile reported count exactly.

## Workflow

1. Read repository instructions and current quality/security/testing skills.
2. Preserve dirty worktree. Audit read-only until user requests implementation.
3. Run:

   ```bash
   node "$CODEX_HOME/skills/audit-slop-prevention/scripts/inventory-history.mjs" \
     --repo "$PWD" --out .audit-slop-prevention
   ```

   If `CODEX_HOME` unset, use `$HOME/.codex`.
4. Verify `summary.json.totalCommits == git rev-list --all --count`. Mismatch → stop; fix inventory.
5. Inventory current controls: agent instructions, agent hooks, Git hooks, package scripts, lint/typecheck/tests, slopgate/config/baselines/suppressions/fixtures, CI workflows, branch protection when accessible. Cite every control/bypass as `path:line` plus exact observed behavior. No exact evidence → mark unverified/deferred.
6. Confirm correction chains. For each candidate, inspect introducing/fixing diffs, blame/history, added tests, escaped gate, and affected invariant. Unknown introducing commit stays `unknown`; NEVER invent agent provenance.
7. Cluster by violated invariant + prevention seam. Same symptom with different invariant stays separate. Require recurrence ≥2 unless severity is auth, money, privacy, data loss, or broad latent blast radius.
8. Backtest proposed deterministic detector:
   - known bad revision MUST fail;
   - parent/valid neighbor MUST pass;
   - fixed revision and current tree MUST pass;
   - false-positive rate MUST be measured, not guessed.
9. Assign cheapest sound layer:

   | Layer | Budget | Allowed work |
   |---|---:|---|
   | Agent instruction | zero runtime | scoped imperative + DO/DO NOT example |
   | Agent hook | <300 ms/file | cached lexical/AST deny checks; no network/tests/history |
   | Pre-commit | <10 s | staged secret/lint/AST/invariant checks |
   | Merge gate | exhaustive | clean-clone full scan, build, DB/browser/concurrency/mutation tests |

10. Require one canonical command per layer. Hooks and CI MUST call repository scripts; NEVER retype divergent check clusters.
11. Write audit using [audit-contract.md](references/audit-contract.md). Include evidence, recurrence counts, representative SHAs, present bypasses, detector matrix, blind spots, rollout, owners, and stopping criteria.
12. Validate report claims against files/commands. Re-open cited lines before finalizing. Report warnings and pre-existing failures; never silently classify noisy green as clean.

## Recurrence protocol

Every confirmed defect fix MUST:

1. Reproduce via red test/fixture.
2. Add or extend detector.
3. Prove green valid/fixed cases.
4. Register stable defect ID, introducing/fixing evidence, detector path, scope, owner.
5. Reject new baseline/suppression unless narrower detector cannot eliminate false positive.

No executable oracle? Add expiring reasoning-checklist entry with evidence required, owner, last-reviewed date, and automation blocker. “Hard,” “slow,” “missing fixture,” or “flaky” are NOT valid blind-spot reasons.

## Required outputs

- `history-inventory.json`: complete commit inventory.
- `correction-candidates.jsonl`: triage queue, not confirmed defects.
- `summary.json`: counts, categories, churn hotspots.
- Audit Markdown: confirmed defect families and prevention architecture.
- Optional implementation plan only when user asks to change repository.

## Stop conditions

- 100% reachable commits inventoried.
- Every high-risk candidate confirmed, rejected with evidence, or explicitly deferred.
- Every recurring/critical family owns regression coverage and gate placement.
- Every proposed rule passes bad/good/fixed backtest.
- Blind spots remain reasoning-only and expire.

## Reject these shortcuts

| Shortcut | Required response |
|---|---|
| Sample recent commits, call it full audit | Inventory `--all`; label sampling honestly. |
| Infer agent authorship from sloppy code | Record provenance `unknown`. Audit defect pattern regardless. |
| Attribute failure policy to wrong CI job | Cite exact `path:line`; otherwise mark unverified. |
| Add prose rule only | Add programmatic detector or justified blind spot. |
| Put heavy tests in edit hook | Move to pre-commit/merge layer. |
| Fail-open prevention hook | Make check available and fail closed; isolate infrastructure failures explicitly. |
| Add new standalone framework | Extend existing linter/slopgate/test stack unless measured gap requires tool. |
| Baseline current violations | Ratchet and remediate; suppression needs narrow evidence. |