scrub · diff

v1.0.0 to v1.0.0

43 added, 140 removed. Audit A to A.

---

name: "scrub"

- description: "Scan recent changes for AI-generated slop -- redundant comments, over-abstraction, generic UI defaults, and design tells -- and optionally apply safe automated fixes. Use after a code-generation or refactor pass to remove the visible signs of machine authorship before review."

+ description: "Scan recent changes for AI-generated slop -- redundant comments, over-abstraction, generic UI defaults, duplicate logic, and design tells -- and optionally apply safe fixes. Use when reviewing a code-generation or refactor pass, before a commit, PR, or merge."

user-invocable: false

metadata:

author: "AgentX"

version: "1.0.0"

created: "2026-05-02"

updated: "2026-05-02"

compatibility:

frameworks: ["agentx", "copilot", "claude-code"]

---

# 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

+ ## Core Rules

- ## When NOT to Use

+ Presentation only, never behavior: comment rot, over-abstraction, generic design defaults, AI filler, and duplicate logic (single-file and cross-file) are in scope; anything that changes runtime semantics is not. **MANDATORY** on every AgentX run that changes files (`... -> implement -> scrub -> test -> review -> ship`); `ship.ps1` always runs it and ignores `-SkipScrub`. See `.github/instructions/project-conventions.instructions.md`.

- - 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

+ ## When to Use / Not Use

- ---

+ Use after generation, refactor, or a large patch; before a PR or review handoff; after approval but before merge; periodically on machine-heavy directories. No prerequisites -- it runs standalone through the AgentX CLI.

+ Skip during active debugging, on intentionally machine-owned output (build artifacts, OpenAPI clients), on vendored files, or as a substitute for behavioral review.

## 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

- 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

- 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. |

+ | Category | Example | Action |

+ |----------|---------|--------|

+ | Comment rot | `// This function handles X`, naked `// TODO` | Delete |

+ | Obvious restatement | `// Increment counter` above `counter++` | Delete |

+ | Dead code | 4+ commented-out code lines | Delete |

+ | AI filler | Empty "Note that"/"To"/"Next" phrasing | Rewrite/delete |

+ | Duplicate logic | Repeated normalized blocks, in-file or cross-file | Flag only |

+ | Over-abstraction | Single-use interface/factory/getter-only class | Flag only |

+ | Generic UI | Purple/blue gradient defaults, lorem ipsum | Flag only |

+ | Stale boilerplate | `Created by ... on ...` | Delete |

+ | Empty try/catch | `catch (e) { }` with no logging | Flag |

- ### 3. Apply Safe Fixes

+ Presentation only; runtime changes go to the reviewer, not scrub.

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

+ ## Cross-File Duplicate Logic

- ```pwsh

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

- ```

+ Directory scans compare normalized 5-line windows across every file, not just within one. Each `duplicate-logic` finding carries both `file`/`line` (the duplicate) and `originalFile`/`originalLine` (the earliest occurrence); other categories emit these two fields as `null`. Traversal is deterministic -- skip-dirs pruned before descending, entries sorted ordinally, reparse points never followed -- so results repeat exactly every run. Adjacent overlapping windows collapse into one finding spanning the full range. Matches only occur within the same language group (ts/tsx/js/jsx together, never vs. py/cs).

- Safe-fix categories (v1):

+ **Ignored as false positives**: structural-only/short blocks (<4 distinct non-keyword tokens), declarative `key: value`/string-list data, vendor/generated dirs (`node_modules`, `dist`, `build`, `.git`, `coverage`; see `$SkipDirs`), and anything behind a symlink or junction.

- - Comment rot in code files

- - Restating the obvious

- - Stale `Created by` / `Last modified by` headers

- - Commented-out code blocks

+ **Not implied by a match**: authorship -- can't be inferred from repeated text; a defect -- shared logic can be intentional; or correctness -- zero findings means none was found, not that code is safe. Never auto-rewritten -- flag-only always; `-Production` only changes whether it blocks the gate.

- Unsafe categories require manual edits and are flag-only:

+ ## Failure Modes: Scan Failures Are Explicit

- - Duplicate logic (requires refactor judgment)

- - Over-abstraction (refactor judgment)

- - Generic UI defaults (brand decisions)

- - Empty try/catch (might be intentional in narrow cases)

+ A missing or unreadable target or nested file fails (exit 2, stderr), never a partial clean result. `-Json` stays an array for zero, one, or many findings on successful scans. Incomplete scans emit no success-shaped findings array.

- ### 4. Verify

+ ## Decision Tree

- After fixes:

+ No qualifying change -> skip. Otherwise scan: flag-only findings need human triage; safe-fix findings can run with `-Fix` and be reviewed before commit.

- - 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>`.

+ ## Workflow

- ---

+ 1. **Scan** via the CLI so it resolves in zero-copy workspaces: `pwsh .agentx/agentx.ps1 scrub -Path src/components`. Production gate (blocks release): `pwsh .agentx/agentx.ps1 deslop -Path src/components -Production` (`antislop` is the same alias).

+ 2. **Triage**: each finding has file/line, category, severity (HIGH auto-fixable, MEDIUM opinionated fix, LOW manual review), snippet, safe-fix flag, and for `duplicate-logic` the original location. `-Production` also blocks on `empty-catch`, `generic-gradient`, and `ai-filler`.

+ 3. **Fix safe categories**: `pwsh .agentx/agentx.ps1 scrub -Path src/components -Fix` applies comment rot, obvious restatement, stale headers, and dead code. Everything else stays flag-only, requiring manual judgment.

+ 4. **Verify**: run tests (behavior must not change); re-scan (remaining findings are the manual-triage list); re-run `-Production` for release candidates; commit as `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

- ---

+ Complete scan, zero HIGH findings and zero required production blockers; tests still pass; the `-Fix` diff is small and mechanical; no behavior change. False positives need documented review, not a silent waiver.

## Anti-Patterns

- - Running `--fix` without reading the scan report first

+ - Running `-Fix` before reading the report

- 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

+ - Treating LOW findings as mandatory

+ - Treating `duplicate-logic` as proof of AI authorship or a defect, or auto-extracting/rewriting the flagged code

- ---

+ ## Rationalization Table

+ | Rationalization | Reality |

+ |-----------------|---------|

+ | "The scanner flagged it twice, so it must be AI-written." | A match is evidence for review, not proof of authorship or a defect; `duplicate-logic` stays flag-only -- never auto-rewrite. |

## Related Skills

- - [Code Hygiene](../code-hygiene/SKILL.md) -- broader cleanup discipline including dead code and over-engineering

- - [Code Review](../code-review/SKILL.md) -- behavioral review that runs alongside scrub

- - [Karpathy Guidelines](../karpathy-guidelines/SKILL.md) -- the underlying behavioral contract that prevents slop in the first place

+ - [Code Hygiene](../code-hygiene/SKILL.md) -- cleanup discipline

+ - [Code Review](../code-review/SKILL.md) -- behavioral review

+ - [Karpathy Guidelines](../karpathy-guidelines/SKILL.md) -- prevents slop