Table of Contents Bloat Categories Quick Start When to Use Confidence Levels Prioritization Module Architecture Safety Bloat Detector
Systematically detect and eliminate codebase bloat through progressive analysis tiers.
Bloat Categories Category Examples Code Dead code, God classes, Lava flow, duplication AI-Generated Tab-completion bloat, vibe coding, hallucinated deps Documentation Redundancy, verbosity, stale content, slop Dependencies Unused imports, dependency bloat, phantom packages Git History Stale files, low-churn code, massive single commits Quick Start Tier 1: Quick Scan (2-5 min, no tools) /bloat-scan
Detects: Large files, stale code, old TODOs, commented blocks, basic duplication
Tier 2: Targeted Analysis (10-20 min, optional tools) /bloat-scan --level 2 --focus code # or docs, deps
Adds: Static analysis (Vulture/Knip), git churn hotspots, doc similarity
Tier 3: Deep Audit (30-60 min, full tooling) /bloat-scan --level 3 --report audit.md
Adds: Cross-file redundancy, dependency graphs, readability metrics
When to Use Do Don't Context usage > 30% Active feature development Quarterly maintenance Time-sensitive bugs Pre-release cleanup Codebase < 1000 lines Before major refactoring Tools unavailable (Tier 2/3) Confidence Levels Level Confidence Action HIGH 90-100% Safe to remove MEDIUM 70-89% Review first LOW 50-69% Investigate Prioritization Priority = (Token_Savings × 0.4) + (Maintenance × 0.3) + (Confidence × 0.2) + (Ease × 0.1)
Module Architecture
Tier 1 (always available):
See modules/quick-scan.md - Heuristics, no tools See modules/git-history-analysis.md - Staleness, churn, vibe coding signatures
Tier 2 (optional tools):
See modules/code-bloat-patterns.md - Anti-patterns (God class, Lava flow) See modules/ai-generated-bloat.md - AI-specific patterns (Tab bloat, hallucinations) See modules/documentation-bloat.md - Redundancy, readability, slop detection See modules/static-analysis-integration.md - Vulture, Knip
Shared:
See modules/remediation-types.md - DELETE, REFACTOR, CONSOLIDATE, ARCHIVE Auto-Exclusions
Always excludes: .venv, pycache, .git, node_modules, dist, build, vendor
Also respects: .gitignore, .bloat-ignore
Safety Never auto-delete - all changes require approval Dry-run support - --dry-run for previews Backup branches - created before bulk changes Related bloat-auditor agent - Executes scans unbloat-remediator agent - Safe remediation context-optimization skill - MECW principles