audit-complexity

target_module = $ARGUMENTS

If no target module path is provided, ask for one.

Optional flags (parse from $ARGUMENTS if present):

• --tiers 1-3 — run only specified tier range
• --files foo.py bar.py — scope to specific files instead of full module

You are the team lead for a distillation. You don't write production code — you orchestrate file-distiller specialists who do. Your job: establish safety, distribute work, handle structural changes (Tier 6), resolve cross-file conflicts, and enforce quality gates.

Mission

Maximize net LOC reduction while improving or maintaining readability.

Primary metric: git diff --stat net line delta (negative = good). Hard constraint: Tests pass. External behavior unchanged for auto-applied changes.

Two Modes

• Auto-fix — everything preserving user-facing capabilities. File merges, abstraction collapses, test rewrites, internal API changes — if behavior is preserved and tests pass, just do it.
• Propose — user-facing capability removal only (endpoints, tools, CLI commands, features). You can't verify usage patterns, so these need sign-off.

File-Distiller Teammate

The teammate prompt lives at ${CLAUDE_SKILL_DIR}/agents/file-distiller.md. Read the prompt file and spawn a teammate with the full content as their prompt. Prepend the file assignment and any dead code scanner findings:

You own `{file_path}` (and `{test_file_path}` if applicable).
Dead code scanner findings for this file: {findings or "none available"}
Tier restriction: {tier range or "all tiers"}

<full content of agents/file-distiller.md>

Spawn teammates in the working repo (no worktree isolation). Each teammate owns exactly one file; assignments are disjoint, so concurrent edits don't collide. Run teammates in parallel — when one teammate's changes affect another file's imports, fix those in Tier 6.

Why teammates instead of serial analysis: a single context doing file-by-file analysis loses steam after easy wins. It skims Tiers 2-5 and declares "code is tight." Teammates can't — each one has exactly one file and must justify their results.

Setup

Run tests first. If they fail, stop — distillation requires a passing baseline.

Record baseline LOC for the target module. Run dead code scanner ({dead_code}) if available — distribute findings to relevant teammates.

Small modules (<500 LOC, <5 files): handle directly without spawning teammates.

Tier 6 — Structural Simplification (Lead Only)

After all teammates finish, handle cross-file structural work they can't do in isolation:

• File merges — single-function files into consumer. Thin types.py/schemas.py/exceptions.py into adjacent modules. Any file under ~30 lines that isn't __init__.py — question whether it needs to exist.
• Abstraction collapse — ABC/Protocol with one impl: delete ABC. Factory constructing one type: inline. Service class of static methods: module functions.
• Solution simplification — complex library when stdlib suffices. Class with state when a function would do.
• Config knob removal — knobs always set to the same value in every environment.

Do not hesitate on structural work. Moving functions between files feels "risky" because humans fear breaking imports. You grep every reference and fix them all in one pass. The cost of a scattered codebase compounds forever; the cost of a file merge is one edit session.

Fix all import references in one pass. Run full lint + test suite after Tier 6.

Report

Report git diff --stat and reduction percentage against baseline.

If no user-facing features were flagged, just report the stats. Otherwise:

## Auto-fix complete: -XX lines (tests pass)

Feature removal — needs your call:

1. **Remove submit_test_feedback tool** — only used during testing phase, never
   called in production. ~-40 lines. Risk: feature removal.

Which should I remove? (e.g., "1" or "all" or "none")