Table of Contents
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) |
When NOT To Use
- Active feature development
- Time-sensitive bugs
- Codebase < 1000 lines
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 scansunbloat-remediator agent - Safe remediationcontext-optimization skill - MECW principles
1---2name: bloat-detector3description: Detect codebase bloat through progressive analysis: dead code, duplication, complexity, documentation bloat. Use when context usage high, quarterly maintenance, pre-release cleanup, before refactoring. Do not use when active feature development, time-sensitive bugs, codebase < 1000 lines.4---5## Table of Contents67- [Bloat Categories](#bloat-categories)8- [Quick Start](#quick-start)9- [When to Use](#when-to-use)10- [Confidence Levels](#confidence-levels)11- [Prioritization](#prioritization)12- [Module Architecture](#module-architecture)13- [Safety](#safety)1415# Bloat Detector1617Systematically detect and eliminate codebase bloat through progressive analysis tiers.1819## Bloat Categories2021| Category | Examples |22|----------|----------|23| **Code** | Dead code, God classes, Lava flow, duplication |24| **AI-Generated** | Tab-completion bloat, vibe coding, hallucinated deps |25| **Documentation** | Redundancy, verbosity, stale content, slop |26| **Dependencies** | Unused imports, dependency bloat, phantom packages |27| **Git History** | Stale files, low-churn code, massive single commits |2829## Quick Start3031### Tier 1: Quick Scan (2-5 min, no tools)32```bash33/bloat-scan34```35Detects: Large files, stale code, old TODOs, commented blocks, basic duplication3637### Tier 2: Targeted Analysis (10-20 min, optional tools)38```bash39/bloat-scan --level 2 --focus code # or docs, deps40```41Adds: Static analysis (Vulture/Knip), git churn hotspots, doc similarity4243### Tier 3: Deep Audit (30-60 min, full tooling)44```bash45/bloat-scan --level 3 --report audit.md46```47Adds: Cross-file redundancy, dependency graphs, readability metrics4849## When To Use5051| Do | Don't |52|----|-------|53| Context usage > 30% | Active feature development |54| Quarterly maintenance | Time-sensitive bugs |55| Pre-release cleanup | Codebase < 1000 lines |56| Before major refactoring | Tools unavailable (Tier 2/3) |5758## When NOT To Use5960- Active feature development61- Time-sensitive bugs62- Codebase < 1000 lines6364## Confidence Levels6566| Level | Confidence | Action |67|-------|------------|--------|68| HIGH | 90-100% | Safe to remove |69| MEDIUM | 70-89% | Review first |70| LOW | 50-69% | Investigate |7172## Prioritization7374```75Priority = (Token_Savings × 0.4) + (Maintenance × 0.3) + (Confidence × 0.2) + (Ease × 0.1)76```7778## Module Architecture7980**Tier 1** (always available):81- See `modules/quick-scan.md` - Heuristics, no tools82- See `modules/git-history-analysis.md` - Staleness, churn, vibe coding signatures8384**Tier 2** (optional tools):85- See `modules/code-bloat-patterns.md` - Anti-patterns (God class, Lava flow)86- See `modules/ai-generated-bloat.md` - AI-specific patterns (Tab bloat, hallucinations)87- See `modules/documentation-bloat.md` - Redundancy, readability, slop detection88- See `modules/static-analysis-integration.md` - Vulture, Knip8990**Shared**:91- See `modules/remediation-types.md` - DELETE, REFACTOR, CONSOLIDATE, ARCHIVE9293## Auto-Exclusions9495Always excludes: `.venv`, `__pycache__`, `.git`, `node_modules`, `dist`, `build`, `vendor`9697Also respects: `.gitignore`, `.bloat-ignore`9899## Safety100101- **Never auto-delete** - all changes require approval102- **Dry-run support** - `--dry-run` for previews103- **Backup branches** - created before bulk changes104105## Related106107- `bloat-auditor` agent - Executes scans108- `unbloat-remediator` agent - Safe remediation109- `context-optimization` skill - MECW principles
jsgforever