home / skills / athola / claude-night-market / bloat-detector

bloat-detector skill

safe

This skill detects and prioritizes codebase bloat through progressive analysis to streamline maintenance and guide safe refactoring.

npx playbooks add skill athola/claude-night-market --skill bloat-detector

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

3.7 KB

---
name: bloat-detector
description: '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.'
category: conservation
tags:
- bloat
- cleanup
- static-analysis
- technical-debt
- optimization
tools:
- Bash
- Grep
- Glob
- Read
modules:
- quick-scan
- git-history-analysis
- code-bloat-patterns
- ai-generated-bloat
- documentation-bloat
- static-analysis-integration
- remediation-types
progressive_loading: true
estimated_tokens: 400
---
## Table of Contents

- [Bloat Categories](#bloat-categories)
- [Quick Start](#quick-start)
- [When to Use](#when-to-use)
- [Confidence Levels](#confidence-levels)
- [Prioritization](#prioritization)
- [Module Architecture](#module-architecture)
- [Safety](#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)
```bash
/bloat-scan
```
Detects: Large files, stale code, old TODOs, commented blocks, basic duplication

### Tier 2: Targeted Analysis (10-20 min, optional tools)
```bash
/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)
```bash
/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 scans
- `unbloat-remediator` agent - Safe remediation
- `context-optimization` skill - MECW principles

Overview

This skill detects and prioritizes codebase bloat through progressive analysis tiers, covering dead code, duplication, complexity, documentation bloat, and dependency noise. It provides quick scans for fast triage, targeted analysis with optional tools, and deep audits that generate actionable reports. Designed for maintenance windows, it recommends safe remediation steps and never auto-deletes without approval.

How this skill works

The tool runs three tiers: a fast heuristic quick scan, a targeted analysis using static tools and git churn signals, and a deep audit that builds cross-file redundancy and dependency graphs. It classifies findings into confidence levels (HIGH/MEDIUM/LOW), scores items for prioritization, and outputs dry-run reports and remediation suggestions. Auto-exclusions and .bloat-ignore rules prevent noise and false positives.

When to use it

Quarterly maintenance and code health reviews
Pre-release cleanup or pre-refactor readiness checks
When runtime or context usage metrics are high (>30%)
Before major refactors to reduce hidden complexity
When you can allocate 10–60 minutes for analysis

Best practices

Run Tier 1 quick scans regularly; use Tier 2/3 for deeper technical debt hunts.
Review MEDIUM and LOW confidence items before removal; prefer refactor or archive over delete.
Use --dry-run and create backup branches before applying bulk changes.
Respect active feature work: avoid running deep audits during time-sensitive development.
Combine static tools (Vulture/Knip) with git-churn signals to reduce false positives.

Example use cases

Find and flag dead functions and large unused modules before a release.
Detect duplicated documentation and reduce verbosity to improve onboarding docs.
Identify unused dependencies and phantom packages to shrink deploy artifacts.
Prioritize remediation candidates by token/maintenance savings for PR planning.
Audit AI-generated code churn for hallucinated dependencies and tab-completion bloat.

FAQ

How confident are the recommendations?

Findings are labeled HIGH, MEDIUM, or LOW confidence. HIGH items (90–100%) are usually safe to remove; MEDIUM should be code-reviewed; LOW requires investigation before action.

Will this skill delete code automatically?

No. It never auto-deletes. Outputs are dry-run reports with suggested actions; actual changes require manual approval or a separate remediation agent.