scrub

Scrub

Purpose: Detect and remove the visible tells of AI-generated code without changing behavior. Scope: Comment rot, over-abstracted code, generic design defaults, AI filler phrasing.

MANDATORY in AgentX: A deslop scrub runs on EVERY AgentX run that changes files, as a required step in the canonical workflow (... -> implement -> scrub -> test -> review -> ship). It is not opt-in. ship.ps1 runs scrub unconditionally; the deprecated -SkipScrub switch is ignored. See the always-on rule in .github/instructions/project-conventions.instructions.md.

---

When to Use This Skill

• Right after a code generation, refactor, or large patch
• Before opening a pull request or a review handoff
• After review approval but before merge -- final polish pass
• Periodically on a directory that has accumulated machine output

When NOT to Use

• During active debugging -- focus on correctness first
• On generated code that is intentionally machine-owned (build output, OpenAPI clients)
• On vendored third-party files
• As a substitute for code review -- scrub catches presentation, review catches behavior

---

What Counts As Slop

Category	Examples	Action
Comment rot	// This function handles the logic for X, // Helper to do thing, naked // TODO	Delete
Restating the obvious	// Increment counter above counter++	Delete
Dead code	Commented-out code blocks of 4+ code-like lines	Delete
AI filler phrasing	Phrases like "Note that", "To", or "Next" when they add no meaning	Rewrite or delete
Duplicate logic	Repeated normalized code blocks within one file	Consolidate manually (flag only)
Over-abstraction	Single-use interface, factory wrapping one constructor, getter-only class	Inline manually (flag only)
Generic UI defaults	bg-gradient-to-r from-purple-500 to-blue-500, placeholder lorem ipsum	Replace with brand palette (flag only)
Stale boilerplate	Created by ... on ..., Last modified by ...	Delete
Empty try/catch	catch (e) { /* ignore */ } with no logging	Flag for review

Code-slop is about presentation, not behavior. Anything that changes runtime semantics is out of scope -- send it to the reviewer.

---

Decision Tree

Recent diff contains machine-generated text?
+- No -> skip
+- Yes -> run scanner
   +- Findings, all in flag categories -> human triage required
   +- Findings, some in safe-fix categories -> run with --fix, review the diff
   +- No findings -> done

---

Workflow

1. Scan

Run the scanner over the directory or files that changed. Invoke it through the agentx CLI so it resolves the bundled scanner in zero-copy workspaces (a literal scripts/scrub.ps1 path does not exist there):

pwsh .agentx/agentx.ps1 scrub -Path src/components

For production-release readiness, use the stricter production gate. It keeps normal scrub behavior advisory for MEDIUM/LOW findings, but blocks release on categories that commonly turn generated code into production maintenance risk:

pwsh .agentx/agentx.ps1 deslop -Path src/components -Production
pwsh .agentx/agentx.ps1 antislop -Path src/components -Production

deslop and antislop are CLI aliases for the same scanner. Use deslop when the main concern is production code hygiene, and antislop when the main concern is AI-generated UI or product-surface tells.

The scanner walks the path, parses comments and content by file extension, and prints findings grouped by category and severity. It does not modify any file in scan mode.

2. Triage

Read the report. Each finding includes:

• File path and line number
• Category and severity
• The exact text that triggered detection
• Whether the category is safe to auto-fix

Findings come in three severities:

Severity	Meaning
HIGH	Almost certainly slop. Auto-fix is safe in supported categories.
MEDIUM	Likely slop. Auto-fix is opinionated; review the diff.
LOW	Possible slop. Manual review only.

In -Production mode, the release gate fails on HIGH findings plus these production-blocking advisory categories:

Category	Why It Blocks Production
duplicate-logic	Repeated validation, mapping, parsing, or error handling can drift after release.
empty-catch	Swallowed failures hide production incidents and make support harder.
generic-gradient	AI-default UI styling is not release-ready without product/design intent.
ai-filler	Filler copy in release docs or product surfaces weakens operator trust.

3. Apply Safe Fixes

Only after reading the report, run with -Fix to apply the auto-safe categories:

pwsh .agentx/agentx.ps1 scrub -Path src/components -Fix

Safe-fix categories (v1):

• Comment rot in code files
• Restating the obvious
• Stale Created by / Last modified by headers
• Commented-out code blocks

Unsafe categories require manual edits and are flag-only:

• Duplicate logic (requires refactor judgment)
• Over-abstraction (refactor judgment)
• Generic UI defaults (brand decisions)
• Empty try/catch (might be intentional in narrow cases)

4. Verify

After fixes:

• Run the test suite. Behavior must not change.
• Re-run the scanner. The remaining findings are the manual-triage list.
• For release candidates, re-run with -Production and clear or justify every production blocker.
• Commit fixes as a single change with chore: scrub <area>.

---

Done Criteria

• Scanner reports zero HIGH findings, or every HIGH finding has been addressed or explicitly justified
• Production-release runs report zero production blockers, or every blocker has a documented release-owner waiver
• Tests still pass after fixes
• Diff from --fix is small, mechanical, and reviewable line-by-line
• No behavior change introduced

---

Anti-Patterns

• Running --fix without reading the scan report first
• Suppressing findings instead of fixing them
• Using scrub to refactor logic -- it is a presentation pass only
• Treating LOW findings as required fixes -- they are signals, not gates

---

Related Skills

• Code Hygiene -- broader cleanup discipline including dead code and over-engineering
• Code Review -- behavioral review that runs alongside scrub
• Karpathy Guidelines -- the underlying behavioral contract that prevents slop in the first place