python-refactor

# Python Refactor

## Purpose

Transform complex, hard-to-understand code into clear, well-documented, maintainable code while preserving correctness. This skill guides systematic refactoring that prioritizes human comprehension without sacrificing correctness or reasonable performance.

## When to Invoke

Invoke this skill when:
- User explicitly requests "human", "readable", "maintainable", "clean", or "refactor" code improvements
- Code review processes flag comprehension or maintainability issues
- Working with legacy code that needs modernization
- Preparing code for team onboarding or educational contexts
- Code complexity metrics exceed reasonable thresholds
- Functions or modules are difficult to understand or modify
- **🚨 RED FLAG: You see any of these spaghetti code indicators:**
  - File >500 lines with scattered functions and global state
  - Multiple `global` statements throughout the code
  - Functions with hard-coded dependencies (no dependency injection)
  - No clear module/class organization
  - Dict/list manipulation instead of proper domain objects
  - Configuration mixed with business logic

Do NOT invoke this skill when:
- Code is performance-critical and profiling shows optimization is needed first
- Code is scheduled for deletion or replacement
- External dependencies require upstream contributions instead
- User explicitly requests performance optimization over readability

## Core Principles

Follow these principles in priority order:

1. **CLASS-BASED ARCHITECTURE IS MANDATORY** - **ALWAYS prefer proper class-based OOP architecture over long messy spaghetti code scripts.** Transform any procedural "script-like" code into well-structured OOP with proper classes, modules, and interfaces. This is NON-NEGOTIABLE.
   - ❌ **NEVER accept**: Globals, scattered functions, 1000+ line scripts, no clear structure
   - ✅ **ALWAYS create**: Classes with clear responsibilities, dependency injection, proper modules
2. **Clarity over cleverness** - Explici