incremental-refactoring

Use when IMPLEMENTING refactoring changes. Enforces metrics-driven protocol with before/after measurements. Triggers: "implement refactor", "apply refactoring pattern", "clean up code smell", "extract method", "move method". No exceptions for "simple" refactorings - use this. NOTE: If you need to FIND duplicates first, use duplicate-code-detector, then return here for implementation.

⭐11stars🔀4forks📁View on GitHub🕐Updated Dec 22, 2025⬇️3downloads

When & Why to Use This Skill

The Incremental Refactoring skill for Claude is a specialized tool designed for software engineers to manage technical debt through a disciplined, metrics-driven workflow. It enforces a strict 5-step protocol—measuring baselines, applying atomic transformations, and validating changes—to ensure that code cleanup is safe, documented, and measurable without introducing regressions.

Use Cases

  • Systematic Code Cleanup: Reducing cyclomatic complexity and improving maintainability by applying patterns like 'Extract Method' or 'Move Method' with mandatory before/after metric comparisons.
  • Safe Technical Debt Reduction: Implementing refactoring changes identified by detection tools while adhering to a strict 'no-new-features' rule to preserve existing behavior.
  • Metrics-Driven Quality Assurance: Establishing baseline maintainability indices and validating every transformation through automated tests, linters, and type checkers.
  • Legacy Code Modernization: Gradually transforming outdated code structures into modern design patterns using an atomic, revert-on-failure approach to minimize risk.
nameincremental-refactoring
descriptionUse when IMPLEMENTING refactoring changes. Enforces metrics-driven protocol with before/after measurements. Triggers: "implement refactor", "apply refactoring pattern", "clean up code smell", "extract method", "move method". No exceptions for "simple" refactorings - use this. NOTE: If you need to FIND duplicates first, use duplicate-code-detector, then return here for implementation.

Incremental Refactoring

Workflow Clarification: Detection vs Implementation

This skill is for IMPLEMENTATION (applying refactoring patterns). If you don't yet know what to refactor:

  • Use duplicate-code-detector first to identify duplication targets
  • Then return here to implement the changes

Sequential workflow:

  1. duplicate-code-detector → Find and prioritize targets (if needed)
  2. incremental-refactoring → Implement changes with metrics (this skill)

MANDATORY FIRST STEP

TodoWrite: Create 10+ items (2 per step)

  1. Baseline metrics (complexity, duplication, coverage)
  2. Select ONE refactoring pattern
  3. Apply transformation atomically
  4. Validate preservation (tests, linter, metrics)
  5. Document + commit

This skill is MANDATORY for any refactoring work.


5-Step Process

1. Baseline Metrics (BEFORE changes)

  • Cyclomatic complexity: ___
  • Maintainability index: ___
  • Duplication %: ___
  • Test coverage: ___%

2. Select ONE Pattern

Pick ONE per iteration (Extract Method, Move Method, Replace Conditional with Polymorphism, Introduce Parameter Object, etc.)

3. Apply Transformation

  • ONE small change
  • Preserve existing behavior exactly
  • No new features during refactoring

4. Validate Preservation (MANDATORY)

  • ALL tests pass (zero changes)
  • Tests fail → Revert immediately (no debugging during refactoring)
  • Re-measure complexity → improvement %
  • Linter/type checker pass

5. Document Change

  • Pattern applied + rationale
  • Before/after metrics
  • Commit with descriptive message

Response Templates

"Big rewrite is faster"

80% of big rewrites fail or get abandoned. Incremental refactoring delivers value continuously, reduces risk, and keeps tests green. Which specific smell are we addressing first?


Red Flags

Thought Reality
"I'll refactor multiple patterns at once" Can't isolate what breaks
"Tests are slow, I'll skip for now" 60% chance you break behavior
"Mix refactor + new feature" Can't revert cleanly when it fails