audit-complexity
This skill contains shell command directives (!`command`) that may execute system commands. Review carefully before installing.
!cat ~/.claude/skills/audit-workflow.md
Run as the complexity dimension. Lens:
Maximize net LOC reduction while readability holds or improves; net git diff --stat delta is the metric, behavior-preservation the hard constraint. Default is DELETE — every line justifies its existence or goes. Auto-fix is anything behavior-preserving: file merges, abstraction collapses, internal API changes, test rewrites. Sign-off is user-facing capability removal only — endpoints, tools, CLI commands, features — where you can't verify usage patterns.
Pretraining biases you toward keeping abstractions: ABCs, factories, service layers, config objects read as "professional." Wrong here — most abstractions in real code serve exactly one call site. Professional = minimal; ceremony = amateur. Rationalizations that all mean DELETE: "separation of concerns" / "common pattern" (common ≠ necessary — name the concrete benefit or cut), "someone might need this flexibility" (they won't, and the pre-built abstraction won't fit when they do), "only a few extra lines" (multiply by every instance), "tests cover it" (covering useless code doesn't make it useful), "already here and working" (sunk cost — wouldn't add it today → delete it today). Removing <15% of a bloated file means you stopped early.
Distillation depth, in yield order:
- Dead code (usually 50%+ of savings). Grep the whole codebase for callers — exports, tests, dynamic references — not just the module. Zero callers + zero coverage → delete, not comment out, not TODO. Caution: dynamically-discovered symbols are live with no static callers — Django models, Flask/decorator registries, React lazy imports, CLI command registries, plugin entry points.
- Premature generalization. Count concrete implementations. One → the abstraction is dead weight. ABC/Protocol w/ one class → delete ABC. Factory building one type → inline. Service class of static methods → module fns. Pass-through wrapper → inline. Single-use util → inline.
- Duplication. Extract only at 4+ lines, 2+ occurrences, ≤2 params. Don't mint new abstractions while killing old ones.
- Defensive bloat. Exception re-wrap w/o added context. Null checks after non-nullable sources. Validation the framework already does (Pydantic/Zod/serde). Try/catch that logs and re-raises unchanged. Defensive copies nobody mutates.
- Surface compression (low yield, high count). Stale
# noqa:, docstrings restating signatures, comments narrating the obvious, single-use intermediates, in-place-obvious constants, multi-line literals that fit on fewer lines. - Structural (cross-file). File merges — single-function files into their consumer; thin
types.py/schemas.py/exceptions.pyinto adjacent modules; any non-__init__.pyfile under ~30 lines: question whether it should exist. Abstraction collapse across modules. Heavy library where stdlib suffices; stateful class where a function would do. Config knobs set to the same value in every environment. Grep every reference and fix all imports in one pass. - Test pruning. Tests for trivial code, files w/ 1–2 tests, test infra heavier than the code under test, tests mirroring implementation.
Never cut: logging lines, type annotations, user-facing schema descriptions, error messages carrying domain context, tests encoding business rules or integration contracts, framework-registered symbols (decorators, route handlers, model classes). Need ~3+ lines saved to justify any readability cost. Don't fight the formatter; don't break encapsulation for LOC.