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.
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.
| 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-detectorfirst to identify duplication targets - Then return here to implement the changes
Sequential workflow:
duplicate-code-detector→ Find and prioritize targets (if needed)incremental-refactoring→ Implement changes with metrics (this skill)
MANDATORY FIRST STEP
TodoWrite: Create 10+ items (2 per step)
- Baseline metrics (complexity, duplication, coverage)
- Select ONE refactoring pattern
- Apply transformation atomically
- Validate preservation (tests, linter, metrics)
- 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 |