Refactor Code

Improve readability, maintainability, and testability without changing behavior.

When to run this skill

• You’ve been asked to clean up tangled logic or long functions
• Technical debt (duplication, inconsistent naming) is slowing future work
• Tests are hard to reason about, or core modules mix responsibilities

Steps

1. Code quality improvements

   • Break large functions or classes into smaller helpers
   • Extract reusable utilities and keep them pure when possible
   • Rename variables/functions to clearly express intent
   • Replace dict/tuple blobs with Pydantic BaseModels where appropriate

2. Reduce complexity

   • Flatten deeply nested conditionals (guard clauses, early returns)
   • Replace repetitive code with loops/fixtures/generator helpers
   • Favor composition over inheritance; inject dependencies explicitly
   • Replace boolean flags with clear strategy objects or enums

3. Enhance maintainability

   • Add or strengthen type hints and docstrings
   • Centralize configuration/timeouts/paths in constants or settings modules
   • Align with SOLID principles when refactoring services or handlers
   • Improve logging and error handling so future debuggers have context

4. Optimize but stay Pythonic

   • Use list/dict comprehensions when they improve clarity
   • Avoid premature micro-optimizations—profile before optimizing loops
   • Keep dependencies explicit instead of hiding global state

Checklist

• Extracted reusable functions or helpers
• Removed duplication and improved naming
• Simplified nested logic and guard clauses
• Added or improved type hints/docstrings
• Tuned logging/error handling to clarify intent
• Ensured tests cover refactored paths