AI Slop Cleaner

A corrective discipline for cleaning AI-generated code. Runs after code generation — whether from

run-plan

, a manual session, or any other source.

The core problem: LLMs produce code that works but carries distinctive smells. Over-commenting, unnecessary abstractions, defensive paranoia for impossible scenarios, verbose naming. Left unchecked, these accumulate into a codebase that is harder to read and maintain than hand-written code.

This skill removes those smells systematically, one category at a time, without changing behavior.

Hard Gates

These rules have no exceptions.

Lock behavior before cleaning. Run existing tests. If coverage is insufficient, add regression tests for the code you're about to touch. No test coverage, no cleanup.
One smell category per pass. Do not mix dead code removal with naming fixes. Complete one pass, verify, then start the next.
Run tests after every pass. If tests fail, revert the pass and investigate. Do not proceed to the next category.
Stay in scope. Only touch files that were generated or modified by AI. Do not expand into "nearby" code that looks like it could use improvement.
Preserve behavior exactly. If a cleanup changes observable behavior — even if you think the new behavior is "better" — revert it. Behavior changes require a separate task.

When To Use

After
```
run-plan
```
completes and the implementation works but reads like AI wrote it
After any significant code generation session
When reviewing AI-generated PRs
When the user explicitly asks to clean up or deslop code

When NOT To Use

Code that was written by humans (different smells, different treatment)
When tests don't exist and can't be added quickly (lock behavior first)
Mid-implementation — finish the feature, then clean

Smell Categories

Passes execute in this order. Each pass completes fully before the next begins.

Pass 1: Dead Code

Remove code that serves no purpose.

Unused imports
Unused variables and parameters
Unreachable branches
Commented-out code blocks
Empty error handlers that swallow exceptions

Detection: compiler warnings, linter output, IDE grayed-out symbols. Trust the tooling.

Pass 2: Over-Commenting

Remove comments that restate what the code already says.

Targets:

// Initialize the counter

above

let counter = 0

```
// Return the result
```
above
```
return result
```
JSDoc that repeats the function signature with no additional insight
Section dividers that add no information (
```
// --- Helper Functions ---
```
)
File headers that describe what is obvious from the filename

Keep: comments that explain why, not what. Comments about non-obvious constraints. Links to external documentation or issues.

Pass 3: Unnecessary Abstractions

Remove indirection that serves no purpose.

Targets:

Helper functions called exactly once (inline them)
Wrapper classes that delegate everything to one inner object
Configuration objects for things that will never be configured
Factory functions that always produce the same thing
Interface/type definitions used by a single implementation with no plans for more

Test: if removing the abstraction makes the code shorter and equally readable, it was unnecessary.

Pass 4: Defensive Paranoia

Remove error handling for scenarios that cannot occur.

Targets:

Null checks on values that are guaranteed non-null by the type system
Try-catch blocks around code that cannot throw
Validation of internal function parameters (validate at system boundaries only)
Fallback values for required fields
Redundant type assertions

Keep: validation at system boundaries (user input, external APIs, file I/O). Error handling where the runtime genuinely can fail.

Pass 5: Verbose Naming

Shorten names that carry redundant information.

Targets:

```
getUserDataFromDatabase
```
→
```
getUser
```
(where else would it come from?)
```
userAccountStatus
```
→
```
status
```
(when used inside a
```
User
```
class, the prefix is redundant)
```
handleButtonClickEvent
```
→
```
onClick
```
```
responseDataObject
```
→
```
response
```
```
tempVariableForCalculation
```
→
```
temp
```
or inline it

Rule: a name should be as short as possible while remaining unambiguous in its scope. Longer scope = longer name. Short scope = short name.

Pass 6: LLM Filler

Remove artifacts of LLM generation style.

Targets:

Emoji in code, comments, or commit messages (unless the project uses them intentionally)
Conversational tone in comments ("Let's", "Now we need to", "Great!")
Excessive
```
console.log
```
/
```
print
```
statements added "for debugging"
Redundant type annotations where inference handles it
Overly structured code that follows a template pattern rather than the natural shape of the problem

Process

text

1. Identify scope (which files to clean)
2. Run existing tests — all must pass before starting
3. Add regression tests if coverage is thin
4. Execute Pass 1 → verify → commit
5. Execute Pass 2 → verify → commit
6. ... continue through all relevant passes
7. Run full test suite
8. Report summary of changes

Not every pass applies to every codebase. Skip passes that have zero findings. But execute in order — never jump ahead.

Anti-Patterns

Impulse	Why It Fails
"I'll clean everything in one big pass"	Mixed changes are impossible to debug when tests break
"This abstraction is bad, let me redesign it"	Redesign is a separate task, not cleanup
"Tests pass, so I'll skip the per-pass verification"	A later pass may interact with an earlier change
"This code nearby also looks sloppy"	Scope creep. Only clean what's in scope
"The behavior is wrong anyway, I'll fix it while cleaning"	Behavior changes require their own task with their own tests
"I don't need regression tests, the code is simple"	Simple code breaks too. Lock behavior first

Red Flags

Stop and reconsider if you catch yourself thinking:

"This is taking too long, let me batch the remaining passes"
"I'll just quickly fix this other file too"
"The tests are probably fine, I don't need to run them again"
"This behavior should be different anyway"
"I don't need tests for this — it's just removing comments"

Completion Standard

Cleanup is done when:

All applicable passes have been executed in order
Tests passed after every individual pass
Full test suite passes at the end
No behavior has changed
Changes are scoped to the identified files only

If any of these are not met, the cleanup is not complete.

Minimal Checklist

During cleanup, verify against this list:

Behavior is locked with tests before starting
Current pass targets one smell category only
Tests passed after the current pass
No files outside the defined scope were touched
No behavior was changed

Transition

After cleanup is complete:

If the code was generated by
```
run-plan
```
→ report results to the user
If implementation discipline was lacking during generation → consider applying
```
karpathy
```
in future sessions to prevent slop at the source

clean-ai-slop

NPX Install

Tags

SKILL.md Content

AI Slop Cleaner

Hard Gates

When To Use

When NOT To Use

Smell Categories

Pass 1: Dead Code

Pass 2: Over-Commenting

Pass 3: Unnecessary Abstractions

Pass 4: Defensive Paranoia

Pass 5: Verbose Naming

Pass 6: LLM Filler

Process

Anti-Patterns

Red Flags

Completion Standard

Minimal Checklist

Transition