bloat-detector

athola's avatarfrom athola

Detect codebase bloat through progressive analysis: dead code, duplication, complexity, and documentation bloat.Triggers: bloat detection, dead code, code cleanup, duplication, redundancy, codebase health, technical debt, unused codeUse when: preparing for refactoring, context usage is high, quarterly maintenance, pre-release cleanupDO NOT use when: actively developing new features, time-sensitive bug fixes.DO NOT use when: codebase is < 1000 lines (insufficient scale for bloat).Progressive 3-tier detection: quick scan → targeted analysis → deep audit.

⭐83stars🔀11forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

Bloat Detector is an advanced Claude skill designed for automated codebase optimization and technical debt reduction. It employs a progressive 3-tier analysis—ranging from quick scans to deep audits—to identify dead code, duplication, complexity, and documentation bloat. By systematically cleaning up repositories, it improves maintainability and optimizes AI context usage for more efficient development.

Use Cases

  • Technical Debt Management: Periodically scan large repositories to identify and prune 'lava flow' patterns, unused functions, and deprecated modules.
  • AI Context Optimization: Reduce the token footprint of a project by eliminating redundant code and documentation, ensuring AI agents operate within context limits more effectively.
  • Pre-Refactoring Audits: Generate comprehensive reports on code complexity and duplication hotspots to inform architectural decisions before major refactoring efforts.
  • AI-Generated Code Cleanup: Detect and remove 'vibe coding' artifacts, hallucinated dependencies, and verbose tab-completion bloat that accumulate during AI-assisted development.
namebloat-detector
description|
Detect codebase bloat through progressive analysisdead code, duplication, complexity, documentation bloat.
Triggersbloat detection, dead code, code cleanup, duplication, technical debt, unused code
Use whencontext usage high, quarterly maintenance, pre-release cleanup, before refactoring
DO NOT use whenactive feature development, time-sensitive bugs, codebase < 1000 lines
categoryconservation
tags[bloat, cleanup, static-analysis, technical-debt, optimization]
tools[Bash, Grep, Glob, Read]
progressive_loadingtrue
estimated_tokens400

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):

  • @module:quick-scan - Heuristics, no tools
  • @module:git-history-analysis - Staleness, churn, vibe coding signatures

Tier 2 (optional tools):

  • @module:code-bloat-patterns - Anti-patterns (God class, Lava flow)
  • @module:ai-generated-bloat - AI-specific patterns (Tab bloat, hallucinations)
  • @module:documentation-bloat - Redundancy, readability, slop detection
  • @module:static-analysis-integration - Vulture, Knip

Shared:

  • @module:remediation-types - 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
  • bloat-auditor agent - Executes scans
  • unbloat-remediator agent - Safe remediation
  • context-optimization skill - MECW principles