/code-slop

Code Slop Detection

Taste-level review of code for AI-generated patterns. Contains 24 rules across 6 categories covering comments, naming, over-engineering, defensive overdose, test slop, and style fingerprints. Where technical-debt measures quantitative code debt (complexity, duplication, CVEs), this skill measures the qualitative failure mode: code that passes every metric but reads like a tutorial blog post, not like a human wrote it.

Metadata

• Version: 1.0.0
• Scope: PHP / Laravel + TypeScript / React (Node)
• Rule Count: 24 rules across 6 categories
• License: MIT

Why this skill exists

Industry data on AI-assisted code (GitClear 2025, cURL bug-bounty shutdown 2025, arXiv 2510.03029):

• Refactoring collapsed from 25% to <10% of changes
• Copy-paste surged 8.3% → 12.3%; code duplication rose ~8x
• Code-smell rates +42–85% over human baselines
• 82% of AI PRs use generic catch blocks that don't distinguish error types
• 76% miss timeouts on external calls

None of this fails a typical CI lint. It just makes the codebase slowly unmaintainable. This skill is the lens for catching it before it ships.

The core insight: reading cost > writing cost now. The cost of writing code collapsed; the cost of reading it didn't. Code you can't quickly understand is slop, even if it works.

How to Audit

When the user asks "review for AI slop", "audit code-quality taste", or "find AI patterns" — run through this skill's rules as a checklist against the changed files (PR diff) or full repo.

Audit Step 1: Determine Scope

• If a PR diff is provided: audit only files changed in the diff
• If files are named: audit those
• If no scope: audit the whole repo, prioritized by recently-touched files (most likely AI output)

Audit Step 2: Detect Stack

Audit Step 3: Run the Slop Checklist

For each item below, output:

• CLEAN — pattern not present (brief confirmation)
• SUSPICIOUS — present in small amounts; flag and discuss
• INFLATED — present extensively; verbose-but-functional; remediation recommended
• CRITICAL — extensive AI-fingerprint presence; full review needed before merge

Comments

• No comments that just narrate the code (// create user above User::create(...))
• No empty docblocks (/** Get user */ above getUser())
• No placeholder comments left in (// TODO: implement, // your code here, // implementation)
• No closing-brace labels (} // end function, } // end if block)

Naming

• No generic placeholder names (data, result, info, temp, helper)
• No over-descriptive run-on names (theUserWhoIsCurrentlyLoggedIn)
• No suffix abuse (*Helper / *Manager / *Util / *Wrapper overused without justification)
• No type-in-name patterns (userObject, resultArray, stringData)

Over-engineering

• No interfaces with exactly one implementation (and no plan for a second)
• No single-method classes that should be top-level functions
• No wrapper functions called once that just delegate
• No new dependency added when an existing one does the same job

Defensive overdose

• No generic catch (e) { console.error(...) } blocks around code that can't throw
• No null checks for impossible nulls (after non-null assertions / type-guaranteed values)
• Real defensive concerns (timeouts on external calls, rate limits) ARE present

Test slop

• No tests that mock every dependency with no real behavioural assertion
• No "doesn't throw" tests that just call and check for exceptions
• No tests that mirror the implementation's logic (re-encoding rather than verifying)
• No snapshot tests standing in for behavioural assertions

Style fingerprints

• Some formatting drift exists (no codebase looks like every file ran through the most aggressive linter)
• No as any / @ts-ignore / @ts-expect-error sprinkled where inference is hard
• Repo has some // HACK: / // XXX: / 2am comments somewhere — codebases without scars are suspect
• No debug artifacts (console.log, var_dump, dd(), dump()) left in production code
• No if (x) return true; else return false / redundant type annotations on obvious literals

Audit Step 4: Build the Slop Ledger

End the audit with a verdict table:

## Code Slop Ledger

| File | Verdict | Top findings | Suggested action |
|------|---------|--------------|------------------|
| app/Services/UserExportService.php | INFLATED | 12 narration comments; 3 closing-brace labels; `*Helper` overuse | Strip comments; rename Helper → split into functions |
| resources/js/Pages/Orders/Show.tsx | CRITICAL | 4 `as any`; mock-everything tests; useless wrapper; impossible null checks | Rewrite section; remove tests; revisit type model |
| app/Models/Order.php | CLEAN | — | — |

## Summary
- CLEAN: X files
- SUSPICIOUS: Y files
- INFLATED: Z files (top priority: …)
- CRITICAL: N files (rewrite before merge)

When to Apply

Reference this skill when:

• Reviewing an AI-assisted PR before merge
• Auditing a repo that has accepted heavy AI-assisted contributions
• Onboarding a codebase and assessing whether it reads as human-maintained
• Hardening a team's code-review checklist against AI slop
• After a "vibe coding" sprint, before declaring features done
• Setting up CI gates for AI-output quality

Step 1: Detect Project Stack

Most rules are stack-agnostic in concept, but examples and detection commands differ between PHP and TypeScript.

Rule Categories by Priority

Quick Reference

1. Comments (CRITICAL)

• comments-narration — Comments that just restate the code on the next line
• comments-empty-docblocks — Generic /** Get the user */ over a typed getUser() signature
• comments-placeholder — // TODO: implement, // your code here, // implementation, // helper function
• comments-closing-brace-labels — } // end function / } // end if block

2. Naming (CRITICAL)

• naming-generic-placeholders — data, result, info, temp, helper, value
• naming-over-descriptive — theUserWhoIsCurrentlyLoggedIn, calculateTotalAmountFromItemsList
• naming-suffix-abuse — *Helper / *Manager / *Util / *Wrapper / *Processor overused
• naming-type-in-name — userObject, resultArray, stringData, listOfItems

3. Over-engineering (HIGH)

• over-eng-premature-interface — Interface with exactly one implementation and no second on the roadmap
• over-eng-single-method-class — Classes that exist solely to wrap one function
• over-eng-useless-wrapper — Wrapper called from exactly one place, just delegating
• over-eng-dependency-creep — New library when an existing dep already does the job

4. Defensive overdose (HIGH)

• defensive-generic-catch — try { ... } catch (e) { console.error("error") } everywhere
• defensive-impossible-null — Null checks after non-null assertions / type-guaranteed values
• defensive-missing-real — Defensive in the wrong places; missing timeouts/rate-limits where it matters

5. Test slop (HIGH)

• test-mock-everything — Mock for every dep; the test re-encodes the implementation, not the behaviour
• test-doesnt-throw — Tests that just call the function and assert no exception
• test-mirror-implementation — Tests whose logic mirrors the production code being tested
• test-snapshot-abuse — Snapshot tests replacing behavioural assertions

6. Style fingerprints (MEDIUM)

• style-hyper-consistent — No formatting drift anywhere; every file looks linter-perfect
• style-as-any-escape — as any / @ts-ignore / @ts-expect-error sprinkled where types are hard
• style-no-hack-scars — Codebase has zero // HACK: / // XXX: markers; no "geology"
• style-debug-artifacts — console.log, var_dump, dd(), dump() left in production paths
• style-trivial-boilerplate — if (x) return true; else return false;, redundant TS type annotations on obvious literals

Essential Patterns

The "would this pass code review?" filter

For each code chunk, ask:

1. Could I cut a third of these comments and the code would be clearer? → likely comment slop
2. Do the variable names tell me what they hold, or just what type they are? → likely naming slop
3. Could this class be a function? → likely over-engineering
4. Does this catch block actually handle anything, or just log? → likely defensive overdose
5. Does this test fail if I break the function? → if no, test slop
6. Are there any // HACK: / // XXX: markers in the diff? → if no, suspicious for AI

Verdict bands (matched to AI-SLOP-Detector's scoring)

How to Use

Read individual rule files for detailed conventions and examples:

rules/comments-narration.md
rules/naming-generic-placeholders.md
rules/over-eng-premature-interface.md
rules/defensive-generic-catch.md
rules/test-mock-everything.md
rules/style-hyper-consistent.md

Each rule file contains:

• YAML frontmatter (title, impact, tags)
• Brief explanation of why the pattern is AI-fingerprint
• "Incorrect" example showing the slop
• "Correct" example showing the human-equivalent
• Detection guidance (grep / eslint / phpstan / heuristic)
• Reference link

References

• GitClear — 2025 Code-Quality Trends Report (refactoring collapse, copy-paste surge)

• arXiv 2510.03029 — Investigating the Smells of LLM-Generated Code

• Addy Osmani — Comprehension Debt (O'Reilly Radar)

• Stack Overflow Blog — Eno Reyes Q&A on AI code quality

• hardikpandya/stop-slop — sister project for prose slop

• flamehaven01/AI-SLOP-Detector — Python AST scanner with 27 patterns

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md