code-humanizer skill

---
name: code-humanizer
version: 0.2.0
description: Use when AI-written code needs structural cleanup or when implementing a change under a guard against AI coding slop — duplicated reimplementations of existing helpers, try-import fallbacks, broad exception swallowing, speculative abstraction layers, _v2 copies, dead "for future use" code, narrating comments — including requests to "deslop", "remove AI slop", "humanize code", review an AI-generated PR beyond tests passing, or prevent these patterns in the current change.
license: MIT
compatibility: any-agent
---

# Code Humanizer

Remove signs of AI-generated code from a repository, or prevent the same patterns in the current change with Guard mode. The prose [humanizer](https://github.com/blader/humanizer) removes AI *writing* patterns; this handles AI *coding* patterns — the structural debt agents leave behind when they optimize for "tests pass" instead of "codebase stays healthy."

**Core principle:** AI code slop is not ugly code — it is code that *works* but degrades the repository: it reimplements what already exists, adds abstraction nobody asked for, swallows errors it should surface, and hedges against situations that cannot occur. Unlike prose, code has an oracle: **the test suite decides what "meaning-preserving" means. Use it constantly.**

## Iron rules

Rules 1–4 govern **cleanup of pre-existing code** in Modes A/B. In Guard mode they apply to any cleanup performed after implementation, not to the requested feature work itself. Rule 5 applies in every mode.

1. **Behavior preservation is absolute.** "Cleanup" that changes behavior is a bug with good intentions. This includes *error types and error timing* — swapping an accidental `AttributeError` for a "nicer" `ValueError` changes behavior for every caller that catches it. If you find a latent bug or an ugly-but-load-bearing behavior: **flag it in the report; never fix it silently as part of cleanup.**
2. **No tests → no cleanup edits.** Run the test suite first. If it doesn't exist, doesn't pass, or doesn't cover the pre-existing code you'd clean, you may only **report** that debt (Mode A). Offer to write characterization tests first. This does not forbid implementing a requested change in a project whose tests are incomplete; report the verification gap.
3. **Report before rewriting pre-existing code.** Default to Mode A (scan → report). Only enter Mode B (fix) when the maintainer approves, or was explicit that they want fixes. Guard mode may directly avoid or remove slop introduced by the current change.
4. **One pattern-class per cleanup commit.** Each commit that removes pre-existing slop handles one kind and passes the full suite. A red test reverts the commit — do not "fix forward" into unrelated code. Ordinary feature commits under Guard mode need not be split by pattern when the prevention is inseparable from the implementation.
5. **Search before you judge duplication.** Build a mental index of the repo's existing helpers *before* scanning or implementing (grep `utils`, `helpers`, `common`, validators, existing base classes). You cannot recognize a reimplementation if you don't know what exists.

## Pattern catalog

Severity per finding: **0** absent · **1** present but justified (→ exempt, do not touch) · **2** minor debt · **3** clear debt, raises future maintenance cost · **4** severe, breaks semantics or architecture boundaries.

### Tier 1 — Duplication and reinvention

**1. Reimplementing an existing helper** *(the signature AI tell)*
**Signals:** new private function whose body resembles something in `utils`/`helpers`/a sibling module; a regex/validation/parsing/formatting block that the repo already owns; new code that imports nothing from the package it lives in.
**Problem:** agents write code from the prompt outward, not from the repo inward. Every duplicate forks future fixes.
```python
# Before — repo already has utils.validate_email
def _is_valid_email(s):
    pattern = r"^[\w.+-]+@[\w-]+\.[\w.]+$"
    if re.match(pattern, s):
        return True
    return False