refactoring-surgeon

Refactor legacy code with small, incremental changes that preserve behavior.

181|30|Updated Nov 16, 2025
One-click install
npx skills add https://github.com/erichowens/some_claude_skills --skill refactoring-surgeon
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: refactoring-surgeon
Source: https://github.com/erichowens/some_claude_skills/tree/main/.claude/skills/refactoring-surgeon
Command: npx skills add https://github.com/erichowens/some_claude_skills --skill refactoring-surgeon

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Expert in code refactoring and software modernization. Helps teams identify and address code smells, apply safe, incremental refactorings, and migrate legacy codebases without changing observable behavior. Provides a structured safety checklist, cross-cut references to proven patterns, and guidance for progressively disclosing complex refactor steps.

Core Features & Use Cases

  • Anti-patterns coverage: Bloaters, OO Abusers, Change Preventers, and more with actionable fixes.
  • Refactoring patterns: Extraction, Movement, Simplification, Organization, and Legacy Migration strategies (e.g., Strangler Fig, Introduce Parameter Object).
  • Safety-first workflow: tests-first approach, change-by-change with clear rollback and documentation.
  • Reference examples: complete "Before" and "After" refactoring examples in ./references/ to aid learning and reproducibility.
  • Dependency-aware guidance: promotes deterministic steps and traceable changes to reduce risk.

Quick Start

Use the refactoring skill to structure a legacy module into smaller, testable pieces and validate behavior after each change.

Frequently Asked Questions about refactoring-surgeon

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

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

Safe refactoring starts with comprehensive test coverage, then applies small, incremental changes—extract method, extract class, or introduce parameter objects—one at a time with validation after each step. This approach preserves behavior while improving code quality and maintainability.

What are code smells and how do I identify them in my codebase?

Code smells are patterns indicating deeper problems: bloaters (long methods, large classes), OO abusers (type checks, switch statements), and change preventers (rigid dependencies). The Skill identifies these anti-patterns and provides actionable fixes aligned with SOLID principles.

How do I migrate a legacy codebase incrementally without a complete rewrite?

Strangler Fig migration progressively replaces legacy components with new implementations in parallel. By introducing parameter objects, extracting testable pieces, and validating behavior preservation at each stage, you reduce risk and maintain system stability throughout modernization.

Can I apply refactoring patterns while maintaining test coverage and traceability?

Yes. The Skill enforces a tests-first workflow with safety checklists and documentation for each change. Cross-reference patterns guide deterministic, traceable refactorings that satisfy SOLID practices and produce measurable quality improvements.

What's the best way to structure refactoring steps for a large, complex module?

Break the module into smaller, testable pieces using extraction patterns—extract method for long functions, extract class for mixed responsibilities. Progressive disclosure of refactor steps, guided by dependency-aware references and before/after examples, reduces complexity and rollback risk.