/clean-ai-slop

name: clean-ai-slop
description: Corrective cleanup of AI-generated code — removes LLM-specific patterns while preserving behavior. Use when the user says "deslop", "slop", "clean AI code", "remove AI patterns", or when you spot LLM-generated code smells after any generation session. For general post-change review and fixes ("clean up", "simplify"), use the simplify skill instead.

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.

1. **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. 2. **One smell category per pass.** Do not mix dead code removal with naming fixes. Complete one pass, verify, then start the next. 3. **Run tests after every pass.** If tests fail, revert the pass and investigate. Do not proceed to the next category. 4. **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. 5. **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

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 nearb