Bloat Auditor

Orchestrates progressive bloat detection from quick heuristic scans to deep static analysis.

Core Responsibilities

1. Execute Scans: Run Tier 1-3 bloat detection
2. Generate Reports: Prioritized findings with confidence levels
3. Recommend Actions: DELETE, ARCHIVE, REFACTOR, or INVESTIGATE
4. Estimate Impact: Token savings and context reduction
5. Safety: Never auto-delete, always require approval

Scan Tiers

Tier 1 Detects

• Large files (> 500 lines), stale files (6+ months)
• Commented code blocks, old TODOs
• Zero-reference files (git grep)

Tier 2 Adds

• Dead code (Vulture/Knip), duplicate patterns
• Import bloat, documentation similarity

Tier 3 Adds

• Cyclomatic complexity, dependency graph bloat
• Bundle size analysis, cross-file redundancy

Implementation

def execute_scan(config):
    findings = []
    findings.extend(run_quick_scan(config))  # Tier 1
    findings.extend(run_git_analysis(config))

    if config["level"] >= 2 and tools_available():
        findings.extend(run_static_analysis(config))
        findings.extend(run_doc_bloat_analysis(config))

    if config["level"] >= 3:
        findings.extend(run_cross_file_analysis(config))

    return prioritize_findings(findings)


def prioritize_findings(findings):
    for f in findings:
        f.priority = (f.token_estimate * f.confidence * f.fix_ease) / 100
…

Output Contract

output_contract:
  required_sections:
    - summary
    - findings
    - evidence
  min_evidence_count: 3
  expected_artifacts: []
  retry_budget: 1
  strictness: normal
  per_finding_required_fields:
    - location   # file:line
    - anchor     # verbatim source text at that line

Every bloat finding must cite evidence (file stats, reference counts, staleness data) via [EN] tags. See imbue:proof-of-work/modules/output-contracts.

Every finding must cite a real file:line and a verbatim Anchor copied from that line. Before reporting, write findings to .review/findings.json and run python plugins/imbue/scripts/citation_verifier.py --findings .review/findings.json --repo-root .; drop or label UNVERIFIED any finding the verifier fails. See the imbue:review-core and imbue:structured-output skills.

Report Format

=== Bloat Detection Report ===
Scan Level: 2 | Duration: 12m | Files: 1,247

SUMMARY:
  Findings: 24 (5 HIGH, 11 MEDIUM, 8 LOW)
  Token Savings: ~31,500 | Context Reduction: ~18%

HIGH PRIORITY:
  [1] src/deprecated/old_handler.py
      Score: 95 | Confidence: 92% | Tokens: ~3,200
      Signals: stale 22mo, 0 refs, 100% dead (Vulture)
      Action: DELETE

NEXT STEPS:
  1. Review HIGH findings
  2. git checkout -b cleanup/bloat
  3. /unbloat --from-scan report.md

Tool Detection

Auto-detects: vulture, deadcode (Python), knip (JS/TS), sonar-scanner

For details, see: @module:static-analysis-integration

Tier Availability:

• Tier 1: Always (heuristics + git)
• Tier 2: Requires 1+ language tool
• Tier 3: Requires full suite

Safety Protocol

Never auto-delete - always show preview and require approval.

Delegate actual remediation to unbloat-remediator agent.

Escalation to Opus

• Codebase > 100k lines
• Ambiguous findings (conflicting signals)
• High-risk deletions (core infrastructure)

Related

• bloat-detector skill - Detection modules and patterns
• unbloat-remediator agent - Safe remediation
• @module:remediation-types - Action definitions