Code Slop Cleanup

Code Slop Cleanup

Strip the residue AI-assisted coding leaves in a branch — obvious comments, defensive theater, debug leftovers, stray files, hedging shims — so the diff that reaches review contains only the change itself. Runs after implementation, before git-workflow/code-reviewing. This pass removes; it never redesigns.

⛔ The Iron Law

Remove only what you can prove is slop — never change behavior. If a removal could change behavior, keep the code and flag it instead.

Slop cleanup that deletes a load-bearing check trades clutter for a bug — a strictly worse codebase. When in doubt, the code stays and the doubt goes in the report.

Workflow

Step 1: Scope the Diff

Branch state vs the default branch (live at skill load):

!git diff main...HEAD --stat 2>/dev/null || git diff master...HEAD --stat 2>/dev/null || true

Run the full git diff <base>...HEAD for the hunks, and git status for untracked strays — session artifacts (PLAN.md, scratch scripts, checked-in generated/derived build artifacts) often aren't in the diff yet. Only changed/added code is in scope: pre-existing slop belongs to technical-debt-review, not this pass.

Step 2: Judge Each Hunk Against Its Surroundings

Slop is relative — the same construct is correct in one place and slop in another. For each candidate, read the surrounding file and ask: is this abnormal for this file's conventions and this codepath's trust level? A try/catch at a process boundary is protection; the same try/catch deep in a validated internal path is theater. See references/slop-patterns.md for the full catalog with per-pattern "when it's NOT slop" columns.

Step 3: Classify by Severity

• High: debug leftovers, silent-failure handlers, stray working files
• Medium: defensive theater on trusted paths, generic TODOs, unrequested backwards-compat shims, duplication of existing helpers
• Medium: also unanchored internal terminology (Phase 2, CP1.3, finding #17) that no git-tracked doc defines — rewrite to the meaning
• Low: comment slop, dead weight (unused imports, === true, redundant returns), style inconsistent with the file

Misplaced rationale — the multi-line header essay explaining a system instead of the code beneath it — is detected here but routed, not deleted: the reasoning belongs in an ADR, and deleting it loses something nothing else records.

Step 4: Strip — Deletions Only, Production Code Only

Apply removals highest severity first. Every edit must be a behavior-preserving deletion (or a trivial inlining a deletion forces). If removing something requires rewriting logic around it, that's refactoring — leave it and flag it.

The two test rules:

1. A test failing after a production-code removal is the oracle saying the removal changed behavior. Revert the removal. Never edit the test.
2. Slop inside test files (redundant tests, trivial asserts, mock-testing) is flagged and routed to test-suite-design — never deleted here. A test's value can't be judged from the diff alone.

Step 5: Re-Run the Tests

Run the project's test suite fresh and read the output (verification-before-completion). Green is the proof the removals were behavior-preserving; a failure means Step 4's rule 1 applies to the offending removal.

Step 6: Report the Tightened Diff

Show what was removed, grouped by category with counts, plus a flagged-not-removed list: anything kept under the Iron Law's doubt clause, test-file slop routed to test-suite-design, suspected bugs routed to code-reviewing/bug-investigating.

Prevention: Reuse Before Write

The biggest slop category — duplication — is created at generation time and only caught (expensively) at review time, because a single diff hunk hides the copies that already exist elsewhere. This is the canonical counter, and code-reviewing points reviewers back here:

• Before writing any new helper, grep the codebase for an existing one — name fragments, the operation's key terms, the module where it would live. AI assistants generate what looks plausible instead of searching for what exists; searching first is the cheap counter.
• Before writing the third near-copy of a block, extract the seam instead. The recurring shapes — an N-arg setup/wiring ritual pasted at every entry point, parallel functions differing only by a noun or constant, byte-identical mappers across sibling modules — are cheap to write locally and expensive to maintain. The moment you're about to paste-and-tweak, that's the signal to factor.

Boundaries — What This Skill Never Does

• Never adds code — no new abstractions, no "while I'm here" improvements.
• Found a bug? Flag it and route to code-reviewing/bug-investigating. Fixing bugs mid-cleanup makes both the cleanup and the fix unreviewable.
• Structural cleanup → refactoring. Most slop cleanup is a micro-refactor, and the two chain naturally: strip slop first, then refactor what remains — but extraction, moving, and re-abstraction are the refactoring skill's discipline (test-protected, one transformation at a time).
• Whole-repo slop → technical-debt-review with its slop debt categories.

Rationalizations to Reject

Red Flags — Stop and Revert

• You modified a conditional's logic instead of deleting something.
• A test failed and you're editing the test.
• You deleted a test.
• You removed validation at a public, API, or user-input boundary.
• You added anything.

Cross-Skill References

• refactoring — structural improvement after the slop is gone; this skill deletes, that one reshapes
• code-reviewing — the review this pass prepares the diff for; bugs found here route there
• test-suite-design — pruning test-file slop with behavior-map proof
• technical-debt-review — repo-scoped slop audit (type/config/doc-drift debt)
• git-workflow — the pre-PR self-review this pass feeds into
• verification-before-completion — the fresh-test-run gate behind Step 5