dancing-bear: Skill for Claude Code

Decompose

Split an oversized Python source or test file into focused submodules. The original module is deleted and every import site is updated to name its new module directly — no re-export facades. The companion workflow workflows/code/decompose-sweep.yaml automates this across an entire domain.

When to Use

• A file exceeds the size thresholds below
• User says "decompose", "split", "break up", or "too large"
• Code review flags a file as too large to review
• Maintenance pass on a domain you're touching anyway

Size Thresholds

Calibrated against the actual file distribution in this repo:

File type	Flag for review	Strong candidate	Split immediately
Source module (src/<domain>/*.py)	500+ lines	700+ lines	900+ lines
Test file (tests/**/*.py)	700+ lines	850+ lines	1000+ lines
Helper/utility module	400+ lines	550+ lines	700+ lines

Rationale: source files in this repo cluster around 400-600 lines with the top 5 ranging 915-1041; test files cluster around 700-900 with the top at 1084. Thresholds are set to catch genuine outliers, not routine files.

Step 1: Identify Candidates

# Find large source files in a domain
find src/<domain>/ -name "*.py" -not -path "*/__pycache__/*" | xargs wc -l | sort -rn | head -20

# Find large test files
find tests/<domain>_tests/ -name "*.py" | xargs wc -l | sort -rn | head -10

# Repo-wide (skip venv, pycache)
find . -name "*.py" \
  -not -path "./.venv/*" \
  -not -path "*/__pycache__/*" \
  -not -path "*/.claude/*" \
  | xargs wc -l | sort -rn | head -20

Step 2: Analyze Structure

Read the full file, then identify:

• Split boundaries: test classes, functional groupings (producers vs consumers), feature areas, command groups
• Shared state: fixtures, base classes, constants, helpers used by multiple groups
• Dependency map: which symbols are imported by other files in the package