hk-slop-audit

Name: hk-slop-audit
Author: deepklarity

84stars12forks

How to install hk-slop-audit?

deepklarity/harness-kit/hk-slop-audit

$npx -y skills add deepklarity/harness-kit --skill hk-slop-audit

Installs into the current project.

Summary

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 slo

Files · 1

View on GitHub

SKILL.md

1	# /hk-slop-audit — Codebase Hygiene Auditor
2
3	Systematically scan the codebase for slop — code that degrades quality through misplacement, abandonment, inconsistency, or negligence. Produce a prioritized, actionable report.
4
5	## Scope
6
7	<audit_scope> $ARGUMENTS </audit_scope>
8
9	If a scope is provided, focus on that directory or category. Otherwise, audit the entire repository.
10
11	## What is slop?
12
13	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.
14
15	## Process
16
17	### Step 1: Map the project structure
18
19	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.
20
21	### Step 2: Scan each category
22
23	Work through each category using parallel subagents where possible. Each subagent scans one category and returns findings.
24
25	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.
26
27	Category 2 — Dead & Orphaned Code: Unused imports, functions nothing calls, commented-out code blocks, orphaned tests for deleted functionality, stale feature flags.
28
29	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.
30
31	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.
32
33	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.
34
35	Category 6 — Dependency Slop: Unused dependencies. Pinned versions with known vulnerabilities. Multiple packages doing the same thing. Dev dependencies in production lists.
36
37	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.
38
39	### Step 3: Verify before reporting
40
41	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.
42
43	### Step 4: Grade each finding
44
45	- P0 — Critical: Active security risk. Committed secrets, exposed credentials, hardcoded tokens.
46	- P1 — High: Actively misleading. Files in wrong directories, dead code developers waste time reading, docs describing wrong behavior.
47	- P2 — Medium: Technical debt that compounds. Duplicated logic, unused dependencies inflating builds, stale configs.
48	- P3 — Low: Code quality friction. Naming inconsistency, oversized files, minor convention violations.
49	- P4 — Trivial: Cosmetic. Extra whitespace, old comments, minor style nits.
50
51	## Output
52
53	### Create `slops/all_slops.md`
54
55	```markdown
56	# Slop Audit — harness-kit
57
58	Audited: [date]
59	Scope: [directories audited]
60	Total findings: [N] (P0: [n], P1: [n], P2: [n], P3: [n], P4: [n])
61
62	## Summary by Priority
63
64	### P0 — Critical
65	\| # \| Finding \| File(s) \| Category \|
66	\|---\|---------\|---------\|----------\|
67
68	[...repeat for each priority level...]
69
70	## Findings by Category
71
72	### Misplaced Files
73	- SLOP-001 — P1 — `path/to/file` — [short description]
74
75	[...repeat for each category with findings...]
76	```
77
78	### Create detail files for P0-P2
79
80	For findings P0, P1, and P2, create `slops/SLOP-NNN-<slug>.md`:
81
82	```markdown
83	# SLOP-NNN: [Short Title]
84
85	Priority: P[0-2]
86	Category: [category name]
87	File(s): `path/to/file`
88	Age: [git blame date or estimate]
89
90	## What's Wrong
91	[2-3 sentences]
92
93	## Evidence
94	[Code snippets, grep results, or structural observations]
95
96	## Suggested Fix
97	[Concrete action]
98
99	## Risk of Fixing
100	[Low/Medium/High — could fixing this break something?]
101	```
102
103	P3 and P4 findings go in the summary only — no individual detail files.
104
105	### Print summary
106
107	After creating all files, print:
108	- Total findings per priority
109	- Top 5 most impactful fixes (best effort-to-impact ratio)
110	- Any categories with zero findings (confirms they were checked)

People who liked this also viewed

6 picks

Type

hk-slop-audit

84stars12forks

View on GitHub

How to install hk-slop-audit?

deepklarity/harness-kit/hk-slop-audit

$npx -y skills add deepklarity/harness-kit --skill hk-slop-audit

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /hk-slop-audit — Codebase Hygiene Auditor
2
3	Systematically scan the codebase for slop — code that degrades quality through misplacement, abandonment, inconsistency, or negligence. Produce a prioritized, actionable report.
4
5	## Scope
6
7	<audit_scope> $ARGUMENTS </audit_scope>
8
9	If a scope is provided, focus on that directory or category. Otherwise, audit the entire repository.
10
11	## What is slop?
12
13	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.
14
15	## Process
16
17	### Step 1: Map the project structure
18
19	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.
20
21	### Step 2: Scan each category
22
23	Work through each category using parallel subagents where possible. Each subagent scans one category and returns findings.
24
25	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.
26
27	Category 2 — Dead & Orphaned Code: Unused imports, functions nothing calls, commented-out code blocks, orphaned tests for deleted functionality, stale feature flags.
28
29	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.
30
31	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.
32
33	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.
34
35	Category 6 — Dependency Slop: Unused dependencies. Pinned versions with known vulnerabilities. Multiple packages doing the same thing. Dev dependencies in production lists.
36
37	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.
38
39	### Step 3: Verify before reporting
40
41	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.
42
43	### Step 4: Grade each finding
44
45	- P0 — Critical: Active security risk. Committed secrets, exposed credentials, hardcoded tokens.
46	- P1 — High: Actively misleading. Files in wrong directories, dead code developers waste time reading, docs describing wrong behavior.
47	- P2 — Medium: Technical debt that compounds. Duplicated logic, unused dependencies inflating builds, stale configs.
48	- P3 — Low: Code quality friction. Naming inconsistency, oversized files, minor convention violations.
49	- P4 — Trivial: Cosmetic. Extra whitespace, old comments, minor style nits.
50
51	## Output
52
53	### Create `slops/all_slops.md`
54
55	```markdown
56	# Slop Audit — harness-kit
57
58	Audited: [date]
59	Scope: [directories audited]
60	Total findings: [N] (P0: [n], P1: [n], P2: [n], P3: [n], P4: [n])
61
62	## Summary by Priority
63
64	### P0 — Critical
65	\| # \| Finding \| File(s) \| Category \|
66	\|---\|---------\|---------\|----------\|
67
68	[...repeat for each priority level...]
69
70	## Findings by Category
71
72	### Misplaced Files
73	- SLOP-001 — P1 — `path/to/file` — [short description]
74
75	[...repeat for each category with findings...]
76	```
77
78	### Create detail files for P0-P2
79
80	For findings P0, P1, and P2, create `slops/SLOP-NNN-<slug>.md`:
81
82	```markdown
83	# SLOP-NNN: [Short Title]
84
85	Priority: P[0-2]
86	Category: [category name]
87	File(s): `path/to/file`
88	Age: [git blame date or estimate]
89
90	## What's Wrong
91	[2-3 sentences]
92
93	## Evidence
94	[Code snippets, grep results, or structural observations]
95
96	## Suggested Fix
97	[Concrete action]
98
99	## Risk of Fixing
100	[Low/Medium/High — could fixing this break something?]
101	```
102
103	P3 and P4 findings go in the summary only — no individual detail files.
104
105	### Print summary
106
107	After creating all files, print:
108	- Total findings per priority
109	- Top 5 most impactful fixes (best effort-to-impact ratio)
110	- Any categories with zero findings (confirms they were checked)

People who liked this also viewed

6 picks

Type