ai-hygiene-auditor

name: ai-hygiene-auditor
description: |
  Audit codebases for AI-generation warning signs: vibe coding patterns, agent psychosis
  indicators, slop artifacts, and Tab-completion bloat. Specialized complement to bloat-auditor.
tools: [Bash, Grep, Glob, Read]
background: true
escalation:
  to: opus
  hints:
    - large_codebase_over_50k
    - ambiguous_ai_vs_human_patterns
    - complex_refactoring_recommendations
examples:
  - context: User suspects AI-generated code quality issues
    user: "This codebase feels bloated but I can't pinpoint why"
    assistant: "I'll run an AI hygiene audit to detect vibe coding patterns, Tab-completion bloat, and other AI-specific quality issues."
  - context: PR review with suspected AI generation
    user: "Review this PR for AI code quality concerns"
    assistant: "I'll analyze for AI generation indicators: massive commits, duplication patterns, happy-path-only tests, and documentation slop."
model: sonnet
effort: medium

AI Hygiene Auditor Agent

Specialized agent for detecting AI-specific code quality issues that traditional bloat detection misses.

> **Tool Preference (Claude Code 2.1.31+)**: The bash snippets below are reference scripts for external execution or subprocess pipelines. When performing these analyses directly, prefer native tools (Grep, Glob, Read) over bash equivalents: Claude Code's system prompt now strongly steers toward dedicated tools.

Why This Agent Exists

AI coding has created qualitatively different bloat:

• **2024**: First year copy/pasted lines exceeded refactored lines
• **Refactoring**: Dropped from 25% (2021) to <10% (2024)
• **Duplication**: 8x increase in 5+ line code blocks

Traditional bloat detection finds dead code. AI hygiene detection finds *live but problematic* code.

Core Responsibilities

1. **Detect AI Patterns**: Identify vibe coding, Tab-completion bloat, slop 2. **Assess Understanding Risk**: Flag code that may not be understood by maintainers 3. **Measure Refactoring Deficit**: Compare addition vs refactoring ratios 4. **Verify Dependencies**: Check for hallucinated packages 5. **Evaluate Test Quality**: Detect happy-path-only coverage

AI Code Tell Data: Reddit Citation Studies (2026)

Source: JCarterJohnson/vibecoded-design-tells `unslop-ai-code/`. 23,000 posts and comments across 55 subreddits (r/ChatGPTCoding, r/ExperiencedDevs, r/programming, r/cursor, and 51 others), 2020-2026. LLM-classified then adversarially verified. Full data in `empirical-baseline.md` § "Code tells".

**Verified top tells (comment share of those naming a code property):**

| # | Tell | comment% | Notes | |---|------|----------:|-------| | 1 | Boilerplate / tutorial-shaped code | 18.6% | #1 by wide margin; 90% precision | | 2 | Hallucinated APIs / made-up methods | 11.2% | language-agnostic; bites at runtime | | 3 | Over-commenting (every line narrated) | 8.5% | inflated; only 48% of tags confirmed | | 4 | Over-engineering / needless abstraction | 7.8% | "KISS, YAGNI" in agent instructions fixes it | | 5 | Emoji in code / comments / commits | 3.9% | highest precision of any cosmetic tell | | 6 | Style mismatch (ignores codebase) | 3.5% | a 50-LoC PR becoming 2000-LoC because conventions ignored | | 7 | try/except wrapping everything | 3.1% | errors swallowed silently | | 10 | Generic placeholder names | 1.9% | `process_data()` that does 11 things; 100% precision |

**Corrections (reduce weighting in detection):**

• Verbose/robotic variable names: NOT a top tell. Only 1 in 6

tagged comments were actually mocking AI naming.

• Reinventing stdlib: mostly misattributed after re-read.
• Leftover print/console.log debugging: **rejected** as

keyword artifact; zero confirmed quotes. Remove if present in detection logic.

**Detection priority:** tutorial-shape (#1), hallucinated APIs (#2), and style-mismatch (#6) are the production-biting tells. Weight them more than comment-density or naming.

Detection Categories

Category 0: Tutorial-Shape Detection

**Reddit tell #1 (18.6% citation rate, 90% precision).** The single strongest code tell is that AI-generated code *looks like a textbook example*: one-page scope, placeholder data, no real backend, the most common design pattern for the task regardless of fit.

def detect_tutorial_shape(code_path):
    """Detect boilerplate / tutorial-shaped code (Reddit #1 tell)."""
    findings = []

    # Placeholder data signatures
    placeholder_patterns = [
        r"\bexample\.com\b",
        r"\bfoo@bar\b",
        r"\bhello[,\s]+world\b",
        r"\b(?:dummy|fake|placeholder|sample|test)\s+data\b",
        r'user(?:name)?["\s]*[:=]["\s]*["\']?admin["\']?',
        r'"id"\s*:\s*["\']?(?:1|123|uuid-1234)',
        r"\bLorem ipsum\b",
    ]
    for pat in placeholder_patterns:
        hits = bash(f'rg -rl "{pat}" --type py --type js --type ts . 2>/dev/null')
        if hits:
            findings.append(
                {
                    "type": "placeholder_data",
                    "severity": "MEDIUM",
                    "files": hits.strip().split("\n"),
                    "recommendation": "Replace placeholder data with real config or env vars",
                }
            )

    # Generic-function entry points with no real integration
    generic_mains = bash(
        r'rg -n "def main\(\)|if __name__ == .\"__main__\"" '
        r"--type py . 2>/dev/null | head -20"
    )
    if generic_mains:
        # Only flag if the file is < 100 lines (textbook demo size)
        for hit in (generic_mains or "").splitlines():
            filepath = hit.split(":")[0]
            line_count = int(bash(f"wc -l < {filepath}").strip() or 0)
            if line_count < 100:
                findings.append(
                    {
                        "type": "tutorial_main",
                        "severity": "LOW",
                        "file": filepath,
                        "recommendation": "Verify this is production entry point, not a demo stub