✂️ 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:
     bash

     mkdir 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

# 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