Incremental Refactoring

name: incremental-refactoring description: 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.

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