Hk Slop Audit

/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

$ARGUMENTS

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 (populatedata, fixmigration, quicktest). 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-.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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: deepklarity
• Source: deepklarity/harness-kit
• License: MIT

Install and usage instructions live in the source repository linked above.