ai-hygiene-auditor

Why this score

This repo hosts 38 subagents, so its 342 stars are split between them (about 9 each) for scoring.

Popularity score: 58/100 from public GitHub signals only. It shows how widely used and maintained this is, not how well it works. Not included yet: the fake-star check. The security scan is shown separately and doesn't change the score. How we rank

What it can use

• ! Run shell commands
• ✓ Read and search files

Tools listed in the file: Bash, Grep, Glob, Read

Model: sonnet

This agent can act outside your files. Read it before installing, and narrow its tools: line if it needs less.

The agent file

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

```python
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",
                    }
                )

    return findings
```

### Category 6b: Style Mismatch Detection

**Reddit tell #6 (3.5% citation rate).** A tell that
scales with project size: AI ignores existing conventions
and invents new ones mid-file. "A PR that should be 50
LoC because it follows existing patterns, versus a 2000
LoC PR that ignores codebase conventions."

```python
def detect_style_mismatch(changed_files, baseline_sample=None):
    """Detect convention breaks vs. the rest of the codebase."""
    findings = []

    # --- Docstring style mismatch ---
    # Detect if changed files use a different docstring format
    # than the rest of the codebase (numpy vs google vs reST)
    repo_docstyle = bash(
        r'rg -l "Parameters\s*\n\s*----------" --type py . | '
        r"head -5"
    )
    numpy_style = bool(repo_docstyle.strip())

    for f in changed_files or []:
        if not f.endswith(".py"):
            continue
        file_has_google = bash(f'rg -l "Args:\\n" {f}').strip()
        if numpy_style and file_has_google:
            findings.append(
                {
                    "type": "docstring_style_mismatch",
                    "severity": "LOW",
                    "file": f,
                    "recommendation": "Use numpy-style docstrings to match the codebase",
                }
            )

    # --- Import style mismatch ---
    # If codebase uses relative imports, new file uses absolute?
    relative_imports = (
        bash(
            r'rg -c "^from \." --type py . 2>/dev/null | '
            r'awk -F: "NR>1{sum+=$2} END{print sum}"'
        ).strip()
        or "0"
    )
    absolute_imports = (
        bash(
            r'rg -c "^from [a-z]" --type py . 2>/dev/null | '
            r'awk -F: "NR>1{sum+=$2} END{print sum}"'
        ).strip()
        or "0"
    )
    # Only flag if the imbalance is severe
    if int(relative_imports) > 3 * int(absolute_imports):
        for f in changed_files or []:
            if f.endswith(".py"):
                uses_absolute = (
                    bash(f'rg -c "^from [a-z]" {f} 2>/dev/null').strip() or "0"
                )
                if int(uses_absolute) > 2:
                    findings.append(
                        {
                            "type": "import_style_mismatch",
                            "severity": "LOW",
                            "file": f,
                            "recommendation": "Codebase uses relative imports; align new file",
                        }
                    )

    return findings
```

### Category 1: Git History Analysis

```python
def analyze_git_patterns(repo_path):
    """Detect vibe coding signatures in git history."""
    findings = []

    # Massive single commits (vibe coding signature)
    massive_commits = bash("""
        git log --oneline --shortstat |
        grep -E '[0-9]{3,} insertion' |
        head -20
    """)
    if massive_commits:
        findings.append(
            {
                "type": "massive_commits",
                "severity": "MEDIUM",
                "evidence": massive_commits,
                "recommendation": "Break into smaller, reviewable commits",
            }
        )

    # Refactoring ratio
    refactor_commits = bash("git log --oneline | grep -ci refactor")
    total_commits = bash("git rev-list --count HEAD")
    ratio = int(refactor_commits) / max(int(total_commits), 1)
    if ratio < 0.05:  # Less than 5% refactoring
        findings.append(
            {
                "type": "refactoring_deficit",
                "severity": "HIGH",
                "metric": f"{ratio:.1%} refactoring commits",
                "recommendation": "Add refactoring to every 4th commit",
            }
        )

    return findings
```

### Category 2: Duplication Analysis

```python
def analyze_duplication(code_path):
    """Detect Tab-completion bloat (repeated similar blocks)."""
    findings = []

    # Run built-in duplicate detector (no external deps required)
    report = bash(
        "python3 plugins/conserve/scripts/detect_duplicates.py . --format json"
    )
    duplicates = json.loads(report)
    if duplicates["summary"]["duplication_percentage"] > 10:
        findings.append(
            {
                "type": "tab_completion_bloat",
                "severity": "HIGH",
                "metric": f"{duplicates['summary']['duplication_percentage']}% duplication",
                "blocks": len(duplicates["duplicates"]),
                "recommendation": "Extract repeated blocks to shared utilities",
            }
        )

    # Heuristic: similar function names
    similar_funcs = bash("""
        grep -rn "^def " --include="*.py" . |
        awk -F'def ' '{print $2}' |
        cut -d'(' -f1 | sort | uniq -c |
        sort -rn | awk '$1 > 2'
    """)
    if similar_funcs:
        findings.append(
            {
                "type": "repetitive_naming",
                "severity": "MEDIUM",
                "evidence": similar_funcs,
                "recommendation": "Review for abstraction opportunities",
            }
        )

    return findings
```

### Category 3: Dependency Verification

```python
def verify_dependencies(project_path):
    """Detect hallucinated packages (slopsquatting risk)."""
    findings = []

    # Python
    if exists("requirements.txt") or exists("pyproject.toml"):
        imports = bash("""
            grep -rh "^import \\|^from " --include="*.py" . |
            sed 's/^import //;s/^from //;s/ import.*//' |
            cut -d. -f1 | sort -u
        """)
        for pkg in imports.split("\n"):
            if not is_stdlib(pkg) and not is_installed(pkg):
                findings.append(
                    {
                        "type": "hallucinated_dependency",
                        "severity": "HIGH",
                        "package": pkg,
                        "recommendation": f"Verify {pkg} exists: pip show {pkg}",
                    }
                )

    # JavaScript
    if exists("package.json"):
        deps = bash("jq -r '.dependencies // {} | keys[]' package.json")
        for pkg in deps.split("\n"):
            if not npm_exists(pkg):
                findings.append(
                    {
                        "type": "hallucinated_dependency",
                        "severity": "HIGH",
                        "package": pkg,
                        "recommendation": f"Verify {pkg} exists: npm view {pkg}",
                    }
                )

    return findings
```

### Category 4: Test Quality Assessment

```python
def assess_test_quality(test_path):
    """Detect happy-path-only tests (AI bias)."""
    findings = []

    # Files without error assertions
    happy_only = bash("""
        grep -rL "Error\\|Exception\\|raises\\|fail\\|invalid" \
            --include="test_*.py" .
    """)
    if happy_only:
        findings.append(
            {
                "type": "happy_path_only",
                "severity": "HIGH",
                "files": happy_only.split("\n"),
                "recommendation": "Add error path tests to each file",
            }
        )

    # Test-to-code ratio
    test_lines = bash(
        "find . -name 'test_*.py' ! -path '*/.venv/*' ! -path '*/__pycache__/*' ! -path '*/node_modules/*' ! -path '*/.git/*' | xargs wc -l | tail -1"
    )
    code_lines = bash(
        "find . -name '*.py' ! -name 'test_*' ! -path '*/.venv/*' ! -path '*/__pycache__/*' ! -path '*/node_modules/*' ! -path '*/.git/*' | xargs wc -l | tail -1"
    )
    ratio = int(test_lines) / max(int(code_lines), 1)
    if ratio < 0.3:  # Less than 30% test coverage by lines
        findings.append(
            {
                "type": "test_deficit",
                "severity": "MEDIUM",
                "metric": f"{ratio:.1%} test-to-code ratio",
                "recommendation": "Target minimum 50% test-to-code ratio",
            }
        )

    return findings
```

### Category 5: Documentation Slop Detection

The quick local check below catches the highest-frequency
hedge patterns. For thorough prose-level scanning
(identity leaks, hallucinations, document-economy,
evidence-backed-claims, anti-goals, the multi-pass cleanup
workflow), delegate to `Skill(scribe:slop-detector)`. This
agent's role is the audit-time triage; scribe is the
detailed scanner.

| For this concern | Delegate to scribe module |
|---|---|
| "As a large language model" leaks | `identity-and-voice-leaks.md` |
| Phantom imports / dead URLs | `hallucination-detection.md` |
| Bare TODOs / "for now" hedges | `stub-and-deferral.md` |
| Unverified "production-ready" claims | `evidence-backed-claims.md` |
| Document buries its thesis | `document-economy.md` |
| What NOT to clean up | `anti-goals.md` |
| 11-pass systematic cleanup | `cleanup-workflow.md` |
| Per-finding output format | `structured-finding-output.md` |
| Research baseline (cite for severity) | `empirical-baseline.md` |

```python
def detect_documentation_slop(docs_path):
    """Detect AI-generated documentation patterns (quick triage).

    For thorough prose scanning, invoke Skill(scribe:slop-detector)
    with the document-economy and identity-and-voice-leaks modules.
    """
    findings = []

    hedge_words = [
        "worth noting",
        "arguably",
        "to some extent",
        "it's important",
        "consider that",
        "generally speaking",
        # 2026 cross-source consensus tells (Wikipedia, Field
        # Guide, Stop-Slop, OliviaCal, George Kao). Quick
        # triage only; delegate full check to scribe.
        "lives in",
        "sits at",
        "stands as",
        "rests on",
        "rooted in",
        "serves as",
        "boasts",
        "here's the thing",
        "let that sink in",
        "the uncomfortable truth is",
        "not just",
        "not only",
        "it's not",
        ", not ",
        "stands as a testament",
        "marks a turning point",
        "underscores the importance",
    ]

    for md_file in glob("**/*.md"):
        content = read(md_file)
        word_count = len(content.split())
        hedge_count = sum(content.lower().count(h) for h in hedge_words)

        if word_count > 100:
            density = (hedge_count * 1000) / word_count
            if density > 15:  # More than 15 per 1000 words
                findings.append(
                    {
                        "type": "documentation_slop",
                        "severity": "LOW",
                        "file": md_file,
                        "metric": f"{density:.0f} hedges per 1000 words",
                        "recommendation": "Rewrite with concrete specifics",
                    }
                )

    return findings
```

### Category 6: Code-Level AI Debt

Detects *live but low-value* code patterns that LLMs produce
at high rates.

```python
def detect_ai_code_debt(code_path):
    """Detect code-level AI generation signatures."""
    findings = []

    # --- Heuristic signals (file-level) ---

    for src_file in glob("**/*.py"):
        content = read(src_file)
        lines = content.splitlines()
        total = len(lines)
        if total < 20:
            continue

        comment_lines = sum(1 for l in lines if l.strip().startswith("#"))
        comment_ratio = comment_lines / total

        funcs = [l for l in lines if l.strip().startswith("def ")]
        func_count = max(len(funcs), 1)

        log_calls = sum(
            1
            for l in lines
            if any(
                p in l
                for p in [
                    "print(",
                    "logging.",
                    "logger.",
                    "console.log",
                    "console.warn",
                    "console.error",
                ]
            )
        )
        log_density = log_calls / func_count

        guard_hits = sum(
            1
            for l in lines
            if any(
                p in l
                for p in [
                    "is None",
                    "is not None",
                    "== None",
                    "!= None",
                    "if not ",
                    "try:",
                    "except Exception",
                    "=== null",
                    "!== null",
                    "=== undefined",
                ]
            )
        )
        guard_density = guard_hits / func_count

        signals = []
        if comment_ratio > 0.30:
            signals.append(f"comment_ratio={comment_ratio:.0%}")
        if log_density > 3.0:
            signals.append(f"log_density={log_density:.1f}")
        if guard_density > 2.0:
            signals.append(f"guard_density={guard_density:.1f}")

        if signals:
            findings.append(
                {
                    "type": "ai_code_debt_signals",
                    "severity": "MEDIUM",
                    "file": src_file,
                    "signals": signals,
                    "recommendation": "Review for AI-generated boilerplate",
                }
            )

    # --- Pattern-based detection (codebase-wide) ---

    # Restating comments: comment that echoes the next line
    # e.g. "# increment counter" above "counter += 1"
    restating = bash("""
        rg -n '^\s*#\s' --type py . |
        head -100
    """)
    # Manual review needed: flag files with >30% comment ratio

    # Docstring bloat on trivial functions (<= 3 lines body)
    # Detected via the comment_ratio heuristic above

    # Pass-through wrappers: functions that just call another
    # function with the same args and no added logic
    passthrough = bash("""
        rg -l 'def \w+\(.*\).*:\s*$' --type py . |
        head -20
    """)
    # Requires manual review of flagged files

    # Generic naming in domain code
    generic_names = bash("""
        rg -n 'def (handle_data|process_item|do_operation|' \
            'handle_request|process_data|manage_items|' \
            'run_task|execute_actio

MIT license, from athola/claude-night-market at commit 9f3eb003bedb.

Security

Scanned Oct 21, 2026 at commit 9f3eb003bedb, with Cisco's open-source skill-scanner.

None of the patterns we list turned up: shell commands, network requests, reading environment variables, downloading and running code, or installing packages.

A scan lists patterns in the code. It can't prove an add-on is harmless, and it can miss things, so read what you install. How we scan

Alternatives

Other makers' add-ons that do the same job, next to this one.