| name | hk-slop-audit |
| description | Run a codebase hygiene audit. Scans for misplaced files, dead code, temp files, security issues, structural problems, dependency slop, and git slop. Outputs a prioritized report with P0-P4 findings. Use periodically or before releases. Triggers on: 'audit the codebase', 'find slop', 'hygiene check', 'clean up', or /hk-slop-audit. |
| argument-hint | [optional: directory or category to focus on] |
| allowed-tools | Bash, Read, Edit, Write, Task, Grep, Glob |
/hk-slop-audit — Codebase Hygiene Auditor
Systematically scan the codebase for slop — code that degrades quality through misplacement, abandonment, inconsistency, or negligence. Produce a prioritized, actionable report.
Scope
<audit_scope> $ARGUMENTS </audit_scope>
If a scope is provided, focus on that directory or category. Otherwise, audit the entire repository.
What is slop?
Slop is anything that makes a developer say "wait, why is this here?" or "is this still used?" It's the entropy that accumulates when people add things but never clean up.
Process
Step 1: Map the project structure
Use Glob and Bash (ls) to understand the directory layout, build systems, and language boundaries. Read the root CLAUDE.md and any project-level CLAUDE.md files to understand intentional patterns — things that look unusual but are deliberate are not slop.
Step 2: Scan each category
Work through each category using parallel subagents where possible. Each subagent scans one category and returns findings.
Category 1 — Misplaced Files: Files in the wrong directory. A Python script in a frontend dir. A test file in src. A config file at the wrong level.
Category 2 — Dead & Orphaned Code: Unused imports, functions nothing calls, commented-out code blocks, orphaned tests for deleted functionality, stale feature flags.
Category 3 — Temp & Scratch Files: Files named temp_, scratch_, debug_, old_, backup_*. One-off scripts (populate_data, fix_migration, quick_test). Log files or build artifacts committed to git.
Category 4 — Security & Config Slop: Hardcoded localhost URLs/ports/credentials. Committed .env files, API keys, tokens. Default passwords in non-example files. Overly permissive CORS/auth settings.
Category 5 — Structural Slop: Duplicate logic across files. Inconsistent naming conventions. God files (>500 lines doing multiple things). Circular imports. Docs describing behavior the code no longer has.
Category 6 — Dependency Slop: Unused dependencies. Pinned versions with known vulnerabilities. Multiple packages doing the same thing. Dev dependencies in production lists.
Category 7 — Git & Project Slop: Files that should be in .gitignore. TODO/FIXME/HACK comments older than 6 months (check git blame). Stale branches referenced in configs.
Step 3: Verify before reporting
Do not flag something as dead code without checking for dynamic imports, reflection, or framework magic. Do not flag a file as misplaced without understanding the project's conventions. Do not flag test fixtures, example files, or template files — they exist for a purpose.
Step 4: Grade each finding
- P0 — Critical: Active security risk. Committed secrets, exposed credentials, hardcoded tokens.
- P1 — High: Actively misleading. Files in wrong directories, dead code developers waste time reading, docs describing wrong behavior.
- P2 — Medium: Technical debt that compounds. Duplicated logic, unused dependencies inflating builds, stale configs.
- P3 — Low: Code quality friction. Naming inconsistency, oversized files, minor convention violations.
- P4 — Trivial: Cosmetic. Extra whitespace, old comments, minor style nits.
Output
Create slops/all_slops.md
# Slop Audit — harness-kit
**Audited**: [date]
**Scope**: [directories audited]
**Total findings**: [N] (P0: [n], P1: [n], P2: [n], P3: [n], P4: [n])
## Summary by Priority
### P0 — Critical
| # | Finding | File(s) | Category |
|---|---------|---------|----------|
[...repeat for each priority level...]
## Findings by Category
### Misplaced Files
- SLOP-001 — P1 — `path/to/file` — [short description]
[...repeat for each category with findings...]
Create detail files for P0-P2
For findings P0, P1, and P2, create slops/SLOP-NNN-<slug>.md:
# SLOP-NNN: [Short Title]
**Priority**: P[0-2]
**Category**: [category name]
**File(s)**: `path/to/file`
**Age**: [git blame date or estimate]
## What's Wrong
[2-3 sentences]
## Evidence
[Code snippets, grep results, or structural observations]
## Suggested Fix
[Concrete action]
## Risk of Fixing
[Low/Medium/High — could fixing this break something?]
P3 and P4 findings go in the summary only — no individual detail files.
Print summary
After creating all files, print:
- Total findings per priority
- Top 5 most impactful fixes (best effort-to-impact ratio)
- Any categories with zero findings (confirms they were checked)
