| name | slop-audit |
| visibility | public |
| triggers | slop, dead code, unused, audit, duplicate, todo, noqa, stale |
| description | 6-lens diagnostic slop audit — unused imports, dead private fns, duplicate signatures, abandoned TODOs, lint bypass markers, stale refs. |
Slop Prevention Audit
Recurring 6-lens scan of core/ / evals/ / evolve/ / scripts/ to catch
the patterns that accumulate during long PR sequences and rot codebase health
when nobody is grepping for them.
When to run
- Per session, before the final PR merges. Catches inline duplicates
and dead-helper candidates introduced during a sprint.
- After a large refactor / removal PR. Surfaces stale references
to the removed feature in unrelated files.
- Before promotion. Use it to find review candidates; its counts do not
decide promotion.
The 6 lenses
| # | Lens | What it surfaces | Severity tier |
|---|
| 1 | unused_imports | ruff F401 — module imports never referenced. | warning |
| 2 | dead_private_functions | def _foo(...) with zero in-file callers. | warning if >10 |
| 3 | duplicate_signatures | Same function name defined in ≥3 files (lift-to-helper signal). | info |
| 4 | abandoned_todos | TODO/FIXME/XXX without owner (name) or YYYY-MM-DD date. | warning if >5 |
| 5 | lint_bypass_markers | # noqa + # type: ignore count. | info |
| 6 | stale_references | Known-removed names that re-appear in source (BudgetGuard, seeds_safe10, etc.). | error if >0 |
Severity is diagnostic. Heuristic absolute counts are not an accepted-debt
floor or promotion contract.
Reading the output
uv run python scripts/slop_audit.py
Emits a markdown report with the count table + first 5 samples per
lens. Inspect samples for patterns:
- unused_imports samples in tests/ → leftover after a refactor.
Auto-fix:
uv run ruff check --fix --select F401.
- dead_private_functions in agent files → same-file textual candidates.
Check cross-module, registry, entrypoint, and compatibility consumers before
changing them.
- duplicate_signatures = "init"/"build"/etc. → expected framework
method. Other shared names still require behavior and caller comparison;
they do not automatically justify a shared helper.
- abandoned_todos → add owner
(@handle) or remove. The convention
is # TODO(@user, 2026-05-18): ....
- stale_references = N for any N > 0 → fix in the same PR as the
feature removal; allowing it to land merges the rot.
Workflow
uv run python scripts/slop_audit.py
The original 2026-05-18 absolute-count snapshot is preserved at
docs/reference/2026-05-18-slop-audit-baseline.md as historical evidence. It
is not a current pass/fail contract. Ruff, mypy, dependency checks, coverage,
and behavior tests remain the promotion gates.
Treat all six lenses as discovery signals. Before deleting code or tests, use
the deletion gate in .agents/skills/agent-anti-pattern/references/field-guide.md.
Stale-reference list
scripts/slop_audit.py maintains _STALE_REFS — a tuple of names
that should not re-appear in production code after their removal PR.
Current list:
BudgetGuard (removed PR 1)SUBAGENT_BUDGET_WARNING (removed PR 1)seeds_safe10 (renamed PR 0)FitnessBaseline (removed S9)plugins.benchmark_harness, plugins.crucible, plugins.petri_audit, and
plugins.seed_generation (removed in v1.0.24)core.self_improving and geode_product (removed in v1.0.24)
Add a new entry whenever you remove a public surface. The lens
ignores docs/ and CHANGELOG.md so historical prose stays
documented. Independent docs/package/install probes mark only their intentional
retirement expectations with # slop:keep.
