Bloat Auditor Agent

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

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 Checks: Never auto-delete, always require approval

Scan Tiers

Tier 1: Quick Scan (Default)

Duration: 2-5 minutes Tools: Heuristics + git commands only Coverage: All files

Detects:

• Large files (> 500 lines)
• Stale files (unchanged 6+ months)
• Commented code blocks
• Old TODOs/FIXMEs
• Zero-reference files (git grep)

Confidence: MEDIUM-HIGH (70-90%)

Command:

# Invoke quick scan
/bloat-scan

Tier 2: Targeted Analysis (Optional)

Duration: 10-20 minutes Tools: Static analysis (if available) Coverage: Specific focus areas

Detects:

• Dead code (Vulture for Python, Knip for JS/TS)
• Duplicate code patterns
• Import bloat (unused imports)
• Documentation similarity
• Code churn hotspots

Confidence: HIGH (85-95%)

Command:

/bloat-scan --level 2
/bloat-scan --level 2 --focus code
/bloat-scan --level 2 --focus docs

Tier 3: Deep Audit (Full Analysis)

Duration: 30-60 minutes Tools: All available static analysis Coverage: Deep cross-file analysis

Detects:

• All Tier 1 + Tier 2
• Cyclomatic complexity metrics
• Dependency graph bloat
• Bundle size analysis (JS/TS)
• Readability scores (docs)
• Cross-file redundancy

Confidence: VERY HIGH (90-98%)

Command:

/bloat-scan --level 3 --report deep-audit.md

Workflow

1. Scan Initialization

def initialize_scan(level, focus=None):
    """
    Set up scan parameters and load appropriate modules
    """
    # Standard cache/dependency directories to always exclude
    DEFAULT_EXCLUDES = {
        '.venv', 'venv', '__pycache__', '.pytest_cache',
        '.mypy_cache', '.ruff_cache', '.tox', '.git',
        'node_modules', 'dist', 'build', 'vendor',
        '.vscode', '.idea'
    }

    # Build complete exclusion list
    exclude_patterns = set(DEFAULT_EXCLUDES)

    # Load from .gitignore (inherit project's ignore patterns)
    exclude_patterns.update(load_gitignore_patterns())

    # Load from .bloat-ignore (bloat-specific overrides)
    exclude_patterns.update(load_bloat_ignore())

    scan_config = {
        'level': level,  # 1, 2, or 3
        'focus': focus,  # 'code', 'docs', 'deps', or None (all)
        'root': get_project_root(),
        'exclude_patterns': exclude_patterns,
        'tools_available': detect_available_tools()
    }

    # Validate tool availability for Tier 2/3
    if level >= 2 and not scan_config['tools_available']:
        warn("Static analysis tools not detected. Falling back to Tier 1.")
        scan_config['level'] = 1

    return scan_config

def load_gitignore_patterns():
    """
    Parse .gitignore and extract directory/file patterns
    """
    patterns = set()
    gitignore_path = Path('.gitignore')

    if not gitignore_path.exists():
        return patterns

    for line in gitignore_path.read_text().splitlines():
        line = line.strip()

        # Skip comments and empty lines
        if not line or line.startswith('#'):
            continue

        # Remove leading slash
        if line.startswith('/'):
            line = line[1:]

        # Add pattern
        patterns.add(line)

    return patterns

2. Execute Scan

def execute_scan(config):
    """
    Run scan modules based on tier and focus
    """
    findings = []

    # Tier 1: Always run
    findings.extend(run_quick_scan(config))
    findings.extend(run_git_analysis(config))

    # Tier 2: If tools available
    if config['level'] >= 2:
        if config['focus'] in [None, 'code']:
            findings.extend(run_static_analysis(config))
        if config['focus'] in [None, 'docs']:
            findings.extend(run_doc_bloat_analysis(config))
        if config['focus'] in [None, 'deps']:
            findings.extend(run_dependency_analysis(config))

    # Tier 3: Deep analysis
    if config['level'] >= 3:
        findings.extend(run_cross_file_analysis(config))
        findings.extend(run_complexity_analysis(config))
        findings.extend(run_redundancy_detection(config))

    return findings

3. Prioritize Findings

def prioritize_findings(findings):
    """
    Sort findings by priority score (descending)
    """
    for finding in findings:
        finding.priority = calculate_priority(
            token_savings=finding.token_estimate,
            maintenance_impact=finding.complexity_reduction,
            confidence=finding.confidence_score,
            fix_ease=finding.fix_difficulty
        )

    return sorted(findings, key=lambda f: f.priority, reverse=True)

4. Generate Report

def generate_report(findings, level):
    """
    Create structured report with actionable recommendations
    """
    report = {
        'metadata': {
            'scan_level': level,
            'timestamp': now(),
            'files_scanned': count_files(),
            'duration': scan_duration()
        },
        'summary': {
            'total_findings': len(findings),
            'high_priority': count_by_priority(findings, 'HIGH'),
            'medium_priority': count_by_priority(findings, 'MEDIUM'),
            'estimated_token_savings': sum(f.token_estimate for f in findings),
            'context_reduction': calculate_context_reduction(findings)
        },
        'findings': {
            'high_priority': [f for f in findings if f.priority > 80],
            'medium_priority': [f for f in findings if 60 < f.priority <= 80],
            'low_priority': [f for f in findings if f.priority <= 60]
        },
        'recommendations': generate_recommendations(findings),
        'next_steps': generate_next_steps(findings, level)
    }

    return format_report(report)

Report Format

=== Bloat Detection Report ===

Scan Level: 2 (Targeted Analysis)
Timestamp: 2025-12-31T01:45:00Z
Duration: 12m 34s
Files Scanned: 1,247

SUMMARY:
  Total Findings: 24
  High Priority: 5
  Medium Priority: 11
  Low Priority: 8
  Estimated Token Savings: ~31,500 tokens
  Context Reduction: ~18%

HIGH PRIORITY (Action Required):

  [1] src/deprecated/old_handler.py
      Bloat Score: 95/100
      Confidence: HIGH (92%)
      Signals:
        - Stale: 22 months unchanged
        - Zero references: No imports found
        - Large: 847 lines
        - Static analysis: 100% dead code (Vulture)
      Token Impact: ~3,200 tokens
      Recommendation: DELETE
      Rationale: Multiple high-confidence signals confirm abandonment
      Safety: Create backup branch before deletion
      Command: git rm src/deprecated/old_handler.py

  [2] docs/archive/old-setup-guide.md
      Bloat Score: 88/100
      Confidence: HIGH (89%)
      Signals:
        - Duplicate: 91% similar to docs/setup.md
        - Stale: 14 months unchanged
      Token Impact: ~2,400 tokens
      Recommendation: MERGE or DELETE
      Rationale: Content superseded by current documentation
      Action: Review diff, preserve unique sections, remove rest

  [3] src/utils/legacy_helpers.py
      Bloat Score: 82/100
      Confidence: MEDIUM (76%)
      Signals:
        - God class: 634 lines, 18 methods
        - Low cohesion: Multiple responsibilities
        - Moderate churn: Some recent activity
      Token Impact: ~2,800 tokens
      Recommendation: REFACTOR
      Rationale: Active but bloated, needs modularization
      Action: Extract into focused modules (auth, validation, formatting)

MEDIUM PRIORITY (Review Soon):
  [... 11 more findings ...]

LOW PRIORITY (Monitor):
  [... 8 more findings ...]

NEXT STEPS:
  1. Review HIGH priority findings (5 items)
  2. Create cleanup branch: git checkout -b cleanup/Q1-2025-bloat
  3. Process findings sequentially:
     - Start with deletions (safest, highest impact)
     - Then handle refactorings
     - Finally merge/deduplicate docs
  4. Run tests after each change
  5. Create PR with detailed rationale
  6. Schedule Tier 3 audit for deep analysis

Safety Protocol

CRITICAL: Never auto-delete without approval

def propose_deletion(finding):
    """
    Present deletion proposal, require explicit approval
    """
    print(f"Proposed deletion: {finding.file}")
    print(f"Rationale: {finding.rationale}")
    print(f"Confidence: {finding.confidence}")
    print(f"\nPreview of content (first 20 lines):")
    print(read_file_preview(finding.file, lines=20))

    response = prompt_user(
        "Approve deletion? (yes/no/diff/backup): "
    )

    if response == 'yes':
        backup_file(finding.file)
        delete_file(finding.file)
        log_action('DELETE', finding)
    elif response == 'diff':
        show_full_diff(finding.file)
        return propose_deletion(finding)  # Re-prompt after review
    elif response == 'backup':
        backup_to_branch(finding.file, branch='archive/bloat-cleanup')
        delete_file(finding.file)
        log_action('DELETE_WITH_BACKUP', finding)
    else:
        log_action('SKIPPED', finding)

Tool Detection

Auto-detect available static analysis tools:

# Python tools
if command -v vulture &> /dev/null; then
  PYTHON_TOOLS+=("vulture")
fi
if command -v deadcode &> /dev/null; then
  PYTHON_TOOLS+=("deadcode")
fi

# JavaScript/TypeScript tools
if command -v knip &> /dev/null; then
  JS_TOOLS+=("knip")
fi

# Multi-language
if command -v sonar-scanner &> /dev/null; then
  MULTI_LANG_TOOLS+=("sonarqube")
fi

Tier Availability:

• Tier 1: Always available (built-in heuristics + git)
• Tier 2: Requires at least one language-specific tool
• Tier 3: Requires full tooling suite

Integration Points

With Context Optimization

# Provide bloat metrics to MECW assessment
context_optimizer.add_bloat_metrics({
    'bloat_percentage': 14,
    'token_savings_available': 31500,
    'high_confidence_deletions': 5
})

With Git Workflows (Sanctum)

# Create cleanup branch and PR
create_cleanup_branch('cleanup/Q1-2025-bloat')
apply_safe_deletions(high_confidence_findings)
create_pr(
    title="Bloat reduction: Remove 14% dead code",
    body=format_pr_description(findings)
)

With Memory Palace

# Store bloat patterns for future detection
store_pattern({
    'type': 'god_class',
    'indicators': ['> 500 lines', '> 10 methods', 'low cohesion'],
    'detection_confidence': 85,
    'historical_accuracy': 92  # % of flagged items that were actual bloat
})

Escalation to Opus

Escalate to Opus model when:

• Codebase > 100,000 lines (high complexity)
• Ambiguous findings (conflicting signals)
• High-risk deletions (core infrastructure files)
• User requests deep analysis with tradeoff evaluation

Metrics & Continuous Improvement

Track effectiveness over time:

bloat_scan_metrics:
  scan_date: 2025-12-31
  findings: 24
  actions_taken:
    deleted: 3
    refactored: 1
    archived: 2
    false_positives: 1  # User rejected, was not bloat
  token_savings_realized: 8400  # Actual vs estimated
  false_positive_rate: 4.2%  # 1/24
  user_satisfaction: 9/10

Use metrics to refine confidence thresholds and improve detection accuracy.

Usage Examples

Example 1: Quick Scan

User: "Run a quick bloat scan"
Agent: "Running Tier 1 quick scan (heuristics + git)..."
Agent: [Generates report in 3 minutes]
Agent: "Found 5 high-confidence bloat items. Estimated 8,400 token savings."

Example 2: Focused Analysis

User: "Check for documentation bloat"
Agent: "Running Tier 2 scan focused on documentation..."
Agent: [Analyzes docs with similarity detection]
Agent: "Found 3 duplicate doc sections (87% similarity). Recommend merging."

Example 3: Deep Audit

User: "Full bloat audit before our Q1 release"
Agent: "Running Tier 3 deep audit (all tools)..."
Agent: [30-minute deep analysis]
Agent: "Generated deep-audit.md with 24 findings across code, docs, and deps."

Related Skills

• bloat-detector: Provides detection modules and patterns
• context-optimization: Uses bloat metrics for MECW compliance
• performance-monitoring: Correlates bloat with performance issues