---

name: Refactor Large File description: Strategy for splitting files >300 lines into cohesive sub-modules.

✂️ Refactoring Skill: Splitting Large Files

Context

Files exceeding 300 lines violate SRP and become hard to maintain. This skill systematically breaks them down.

Steps

1. Analyze Responsibilities:

   • Identify distinct clusters of logic (e.g., UI Components vs Event Handlers vs Helper Functions).
   • Use view_file_outline to visualize class/function groups.

2. Create Package Structure:

   • If module.py is the target:

     Copymkdir module_pkg
     mv module.py module_pkg/__init__.py
     

   • Or prefer creating specific files: helpers.py, constants.py, types.py.

3. Move & Isolate:

   • Move code chunks to new files.
   • CRITICAL: Ensure imports in new files are correct.
   • CRITICAL: Re-export moved classes in __init__.py to maintain backward compatibility if needed, OR update all consumers (preferred).

4. Verify:

   • Run uv run pytest immediately.
   • Check for circular imports (common risk).

Example Command Sequence

Copy# 1. Create sub-modules
New-Item -Path "src/core/complex_module/types.py" -Force
New-Item -Path "src/core/complex_module/logic.py" -Force

# 2. Update __init__.py to export public API
echo "from .types import *" > src/core/complex_module/__init__.py
echo "from .logic import *" >> src/core/complex_module/__init__.py