/bloat-scan

name: bloat-scan
description: Scan for codebase bloat using 3-tier progressive analysis: dead code, duplication, God classes, and documentation waste.
usage: /bloat-scan [--level 1|2|3] [--focus code|docs|deps] [--report FILE] [--dry-run]
# Claude Code 2.1.0+ lifecycle hooks
hooks:
  PreToolUse:
    - matcher: "Task"
      command: |
        # Log scan initiation with parameters
        echo "[cmd:bloat-scan] 🔍 Bloat scan started at $(date) | User: ${USER:-unknown}" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        # Track scan level (indicates concern depth)
        if echo "$CLAUDE_TOOL_INPUT" | grep -qE "level"; then
          level=$(echo "$CLAUDE_TOOL_INPUT" | grep -oP 'level["\s:=]+\K[123]' || echo '1')
          echo "[cmd:bloat-scan] Scan level: $level (1=quick, 2=targeted, 3=deep audit)" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        fi
        # Track focus area
        if echo "$CLAUDE_TOOL_INPUT" | grep -qE "focus"; then
          focus=$(echo "$CLAUDE_TOOL_INPUT" | grep -oP 'focus["\s:=]+\K\w+' || echo 'all')
          echo "[cmd:bloat-scan] Focus: $focus" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        fi
      once: true
  Stop:
    - command: |
        echo "[cmd:bloat-scan] === Scan completed at $(date) ===" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        # Track: bloat scan frequency = technical debt awareness metric

Bloat Scan Command

Execute progressive bloat detection across code, documentation, and dependencies.

Usage

# Quick scan (Tier 1, default)
/bloat-scan

# Targeted analysis (Tier 2)
/bloat-scan --level 2
/bloat-scan --level 2 --focus code
/bloat-scan --level 2 --focus docs

# Deep audit (Tier 3)
/bloat-scan --level 3 --report audit-report.md

# Dry run (no changes)
/bloat-scan --dry-run

Options

| Option | Description | Default | |--------|-------------|---------| | `--level <1|2|3>` | Scan tier: 1=quick, 2=targeted, 3=deep | `1` | | `--focus <type>` | Focus area: `code`, `docs`, `deps`, or `all` | `all` | | `--report <file>` | Save report to file | stdout | | `--dry-run` | Preview findings without taking action | false | | `--exclude <pattern>` | Additional exclude patterns beyond defaults | `.bloat-ignore` | | `--growth [path]` | Run growth velocity analysis on path | cwd | | `--threshold <lines>` | Override default line limit for threshold alerts | varies by file type | | `--compare` | Compare before/after optimization (use with `--growth`) | false |

**Note**: Cache directories (`.venv/`, `node_modules/`, `.pytest_cache/`, etc.) are automatically excluded from all scans.

Scan Tiers

Tier 1: Quick Scan (2-5 min)

**Detects:**

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

**Requirements:** None (heuristics and git)

Tier 2: Targeted Analysis (10-20 min)

**Detects:**

• Dead code (static analysis)
• Duplicate patterns
• Import bloat
• Documentation similarity
• Code churn hotspots

**Requirements:** Optional static analysis tools (Vulture, Knip)

Tier 3: Deep Audit (30-60 min)

**Detects:**

• All Tier 1 + Tier 2
• Cyclomatic complexity
• Dependency graphs
• Bundle size analysis
• Readability metrics

**Requirements:** Full tooling suite

Workflow

1. **Invoke Command**

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

2. **Agent Executes Scan**

• Dispatches `bloat-auditor` agent
• Loads `bloat-detector` skill modules
• Runs detection algorithms

3. **Generate Report**

   === Bloat Detection Report ===

   Scan Level: 2
   Files Scanned: 847
   Findings: 24

   HIGH PRIORITY (5):
     - src/deprecated/old_handler.py (95/100)
     - docs/outdated-migration-guide.md (88/100)
     ...

   MEDIUM PRIORITY (11):
     ...

   STATS:
     Estimated bloat: 14%
     Token savings: ~31,500
     Context reduction: ~12%

4. **Review & Approve Actions**

• User reviews high-priority findings
• Approves deletions/refactorings
• Agent executes approved changes

Output Format

Terminal Output

🔍 Running Bloat Scan (Tier 1)...

[████████████████████] 847 files scanned (5.2s)

✅ Scan complete!

HIGH PRIORITY (Immediate Action):
  ❌ src/deprecated/old_handler.py
     Score: 95/100 | Confidence: HIGH
     Signals: Stale (22mo), Unused (0 refs), Large (847 lines)
     Impact: ~3,200 tokens
     Action: DELETE

MEDIUM PRIORITY (Review Soon):
  ⚠️  src/utils/helpers.py
     Score: 76/100 | Confidence: MEDIUM
     Signals: God class (634 lines), Low cohesion
     Impact: ~2,800 tokens
     Action: REFACTOR

SUMMARY:
  • Total findings: 24
  • High priority: 5
  • Token savings: ~31,500 (12% reduction)

NEXT STEPS:
  1. Review HIGH priority items (5 findings)
  2. Run: git checkout -b cleanup/bloat-reduction
  3. Process findings sequentially

Report File (--report)

# Bloat Detection Report

**Scan Date:** 2025-12-31
**Level:** 2 (Targeted Analysis)
**Duration:** 12m 34s
**Files Scanned:** 847

## Summary

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

## High Priority Findings

### [1] src/deprecated/old_handler.py

**Bloat Score:** 95/100
**Confidence:** HIGH (92%)

**Signals:**
- Stale: 22 months unchanged
- Unused: 0 references found
- Large: 847 lines
- Dead code: 100% (Vulture)

**Token Impact:** ~3,200 tokens

**Recommendation:** DELETE

**Rationale:** Multiple high-confidence signals confirm complete abandonment. No active usage detected.

**Action Plan:**
```bash
# Create backup
git checkout -b backup/old-handler
git add src/deprecated/old_handler.py
git commit -m "Backup before deletion"

# Delete on main branch
git checkout main
git rm src/deprecated/old_handler.py
git commit -m "Remove deprecated handler (bloat scan #1)"

[... more findings ...]

Next Steps

1. ✅ Review all HIGH priority findings