safe-refactoring_skill

Overview

This skill performs systematic, behavior-preserving code refactoring to improve structure, readability, and maintainability without changing external behavior. It guides identification of code smells, plans safe refactoring sequences, executes single-step refactorings, and validates behavior via tests. The process enforces strict checks and rollback on any behavioral drift.

How this skill works

The skill first establishes a baseline by running existing tests, measuring coverage, and documenting uncovered behavior. It analyzes code using a catalog of code smells, prioritizes refactorings by independence, risk, and impact, then applies one atomic change at a time. Each change is followed by immediate test execution; failures trigger an immediate revert and investigation. A final validation runs the full suite and compares behavior to the baseline.

When to use it

• When you detect code smells such as long methods, duplication, or complex conditionals
• When planning a safe sequence of structural improvements across multiple files
• Before performing renames, moves, or method extractions to ensure no behavior changes
• When you need to validate that refactoring did not alter business logic or external APIs
• When delegating refactoring tasks to agents and requiring strict behavior preservation

Best practices

• Always run and document baseline tests and coverage before any change
• Make one refactoring change per cycle and run tests immediately after
• Order refactorings by independence, lowest risk, and building-block impact
• Use automated IDE refactors for renames and moves to avoid missing callers
• Add tests for uncovered behavior before refactoring high-risk areas
• Revert immediately on failing tests and investigate root cause before retrying

Example use cases

• Extracting smaller methods from a long function while keeping behavior identical
• Introducing a parameter object to reduce long parameter lists without changing API contracts
• Moving a method to a more appropriate class to fix feature envy while updating callers and running tests
• Renaming unclear variables and functions using IDE support to improve readability safely
• Planning and executing a multi-step refactor across a module with risk-ordered steps and checkpoints