refactoring_skill

Overview

This skill detects common code smells and generates safe, actionable refactoring guidance for Python and other supported languages. It identifies problematic patterns, proposes prioritized refactoring plans, and can apply or validate refactorings when tests or risk parameters permit. The goal is to reduce technical debt while preserving behavior.

How this skill works

The skill analyzes source code with an AST-based smell detector to find categories like bloaters, couplers, dispensables, and change-preventers. For a requested action (detect, plan, apply, validate) it returns detected smells, a refactoring plan with recommended techniques (e.g., Extract Method, Move Method), refactored code when safe, and validation results against tests or heuristics. It respects configurable risk tolerance and test coverage to avoid unsafe changes.

When to use it

• Before major feature work to reduce the chance of regressions caused by complex code
• During code review to provide automated, prioritized refactoring suggestions
• When preparing legacy code for extension or integration
• To generate safe, test-driven refactor plans for long methods or large classes
• When validating that an automated refactor preserved behavior with available tests

Best practices

• Provide at least partial test coverage before applying risky refactors; prefer low/medium risk actions when tests are absent
• Limit refactoring scope per run (single method or class) to keep changes reviewable and reversible
• Use the plan action to preview steps and filenames before applying code modifications
• Configure smell categories to focus on the most relevant issues for the codebase (e.g., couplers vs bloaters)
• Run validation after apply to confirm behavior unchanged and update tests if needed

Example use cases

• Detect and report Long Method and Long Parameter List in a legacy Python module
• Generate a step-by-step Extract Method plan for a 60-line function, including test checkpoints
• Apply safe refactorings for low-risk transformations when full test coverage exists
• Validate that recent refactors did not introduce behavioral changes using provided tests
• Prioritize refactoring work by severity and risk tolerance for sprint planning