incremental-refactoring

Prioritize and implement behavior-preserving code refactorings with user approval and test verification.

23|7|Updated Sep 8, 2025
One-click install
npx skills add https://github.com/pvillega/claude-templates --skill incremental-refactoring
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: incremental-refactoring
Source: https://github.com/pvillega/claude-templates/tree/main/plugins/ct/skills/incremental-refactoring
Command: npx skills add https://github.com/pvillega/claude-templates --skill incremental-refactoring

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps developers improve code structure, readability, and maintainability by performing small, behavior-preserving refactorings instead of large, risky rewrites. It reduces risk by insisting on an analysis-only phase, explicit user approval, and single-transformation commits with verification after each change.

Core Features & Use Cases

  • Two-phase workflow: analyze and prioritize candidate refactorings (80/20), then perform one approved transformation per cycle.
  • Safe transformation catalog: extract method, inline method, rename, move function, extract variable, replace nested conditionals, split loops, and similar verifiable edits.
  • Verification-first: require tests, type checks, or mechanical equivalence proofs after each change and commit one transformation at a time.
  • Use Case: Incrementally clean up a long, complex function by extracting methods and validating with unit tests between each commit.

Quick Start

Ask the skill to analyze the codebase and present HIGH priority refactoring candidates following the Incremental Refactoring guide and await approval before making changes.

Frequently Asked Questions about incremental-refactoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I safely refactor legacy code without breaking existing behavior?

Safe code refactoring requires an analysis-only phase to prioritize candidates, explicit user approval before edits, and single-transformation commits verified by tests or type checks to ensure behavior remains unchanged.

What is the best way to reduce deep nesting and complex conditionals in a large function?

The best way to reduce nesting and complex conditionals is through incremental code refactoring, applying verifiable transformations like extract method or replace nested conditionals one step at a time with tests validating each change.

How do I prioritize which code smells to fix first during a code cleanup?

Prioritizing code smells during cleanup involves applying an 80/20 analysis phase to identify and rank candidate refactorings, focusing on high-impact structural improvements before performing any actual code edits.

Can I refactor code safely if my project only uses type checking instead of unit tests?

Yes, you can safely refactor code if your project relies on type checking, because the verification process accepts either passing tests or mechanical type checks after each single-transformation commit to prove behavior is preserved.

When should I avoid incremental refactoring and do a full rewrite instead?

You should avoid incremental refactoring when large, risky rewrites are explicitly preferred over small verifiable transformations, or when your codebase lacks tests and type checks to mechanically verify behavior after each change.