Comprehensive refactoring skill covering safe transformation patterns, code smell detection, dead code elimination, and test-driven refactoring methodology.
Refactoring Decision Tree
What kind of refactoring do you need?
│
├─ Extracting code into a new unit
│ ├─ A block of statements with a clear purpose
│ │ └─ Extract Function/Method
│ │ Identify inputs (params) and outputs (return value)
│ │
│ ├─ A UI element with its own state or props
│ │ └─ Extract Component (React, Vue, Svelte)
│ │ Move JSX/template + related state into new file
│ │
│ ├─ Reusable stateful logic (not UI)
│ │ └─ Extract Hook / Composable
│ │ React: useCustomHook, Vue: useComposable
│ │
│ ├─ A file has grown beyond 300-500 lines
│ │ └─ Extract Module
│ │ Split by responsibility, create barrel exports
│ │ Watch for circular dependencies
│ │
│ ├─ A class does too many things (SRP violation)
│ │ └─ Extract Class / Service
│ │ One responsibility per class, use dependency injection
│ │
│ └─ Magic numbers, hardcoded strings, env-specific values
│ └─ Extract Configuration
│ Constants file, env vars, feature flags
│
├─ Renaming for clarity
│ ├─ Variable, function, or method
│ │ └─ Rename Symbol
│ │ Update all references (IDE rename or ast-grep)
│ │
│ ├─ File or directory
│ │ └─ Rename File + Update Imports
│ │ git mv to preserve history, update all import paths
│ │
│ └─ Module or package
│ └─ Rename Module + Update All Consumers
│ Search for all import/require references
│ Consider re-exporting from old name temporarily
│
├─ Moving code to a better location
│ ├─ Function/class to a different file
│ │ └─ Move + Re-export from Original
│ │ Leave re-export for one release cycle
│ │
│ ├─ Files to a different directory
│ │ └─ Restructure + Update All Paths
│ │ Use IDE refactoring or find-and-replace
│ │
│ └─ Reorganize entire directory structure
│ └─ Incremental Migration
│ Move one module at a time, keep tests green
│
├─ Simplifying existing code
│ ├─ Function is too simple to justify its own name
│ │ └─ Inline Function
│ │ Replace call sites with the body
│ │
│ ├─ Variable used only once, right after assignment
│ │ └─ Inline Variable
│ │ Replace variable with expression
│ │
│ ├─ Deep nesting (> 3 levels)
│ │ └─ Guard Clauses + Early Returns
│ │ Invert conditions, return early
│ │
│ └─ Complex conditionals
│ └─ Decompose Conditional
│ Extract each branch into named function
│
└─ Removing dead code
├─ Unused imports
│ └─ Lint + Auto-fix (eslint, ruff, goimports)
│
├─ Unreachable code branches
│ └─ Static analysis + manual review
│
├─ Orphaned files (no imports point to them)
│ └─ Dependency graph analysis (knip, ts-prune, vulture)
│
└─ Unused exports
└─ ts-prune, knip, or manual grep for import references
Safety Checklist
Run through this checklist before starting any refactoring:
Pre-Refactoring
[ ] All tests pass (full suite, not just related tests)
[ ] Working tree is clean (git status shows no uncommitted changes)
[ ] On a dedicated branch (not main/master)
[ ] CI is green on the base branch
[ ] You understand what the code does (read it, don't assume)
[ ] Characterization tests exist for untested code you will change
During Refactoring
[ ] Each commit compiles and all tests pass
[ ] Commits are small and focused (one refactoring per commit)
[ ] No behavior changes mixed with structural changes
[ ] Running tests after every change (use --watch mode)
Post-Refactoring
[ ] Full test suite passes
[ ] No new warnings from linter or type checker
[ ] Code review requested (refactoring PRs need fresh eyes)
[ ] Performance benchmarks unchanged (if applicable)
[ ] Documentation updated (if public API changed)
Extract Patterns Quick Reference
Pattern
When to Use
Key Considerations
Extract Function
Block of code has a clear single purpose, used or could be reused
Name should describe WHAT, not HOW. Pure functions preferred.
Extract Component
UI element has own state, props, or rendering logic
Props interface should be minimal. Avoid prop drilling.
Extract Hook/Composable
Stateful logic shared across components
Must start with use. Return stable references.
Extract Module
File exceeds 300-500 lines, has multiple responsibilities
One module = one responsibility. Barrel exports for public API.
Extract Class/Service
Object handles too many concerns
Dependency injection over hard-coded dependencies.
String references (logs, error messages) not caught by IDE
Class/type
IDE rename + update file name to match
Serialized data may reference old name (JSON, DB)
File
git mv old new + update all imports
Import paths in test files, storybook, config files often missed
Directory
git mv + bulk import update
Barrel re-exports, path aliases in tsconfig/webpack
Package/module
Rename + re-export from old name
External consumers need deprecation period
Move/Restructure Quick Reference
Scenario
Strategy
Safety Net
Single file move
git mv + update imports + re-export from old path
rg 'old/path' to find all references
Multiple related files
Move together, update barrel exports
Run type checker after each move
Directory restructure
Incremental: one directory per PR
Keep old paths working via re-exports
Monorepo package split
Extract to new package, update all consumers
Version the new package, pin consumers
Dead Code Detection Workflow
Step 1: Automated Detection
│
├─ TypeScript/JavaScript
│ ├─ knip (comprehensive: files, deps, exports)
│ │ └─ npx knip --reporter compact
│ ├─ ts-prune (unused exports)
│ │ └─ npx ts-prune
│ └─ eslint (unused vars/imports)
│ └─ eslint --rule 'no-unused-vars: error'
│
├─ Python
│ ├─ vulture (dead code finder)
│ │ └─ vulture src/ --min-confidence 80
│ ├─ ruff (unused imports)
│ │ └─ ruff check --select F401
│ └─ coverage.py (unreachable branches)
│ └─ coverage run && coverage report --show-missing
│
├─ Go
│ └─ staticcheck / golangci-lint
│ └─ golangci-lint run --enable unused,deadcode
│
├─ Rust
│ └─ Compiler warnings (dead_code, unused_imports)
│ └─ cargo build 2>&1 | rg 'warning.*unused'
│
Step 2: Manual Verification
│ ├─ Check if "unused" code is used via reflection/dynamic import
│ ├─ Check if exports are part of public API consumed externally
│ ├─ Check if code is used in scripts, tests, or tooling not in the scan
│ └─ Check if code is behind a feature flag or A/B test
│
Step 3: Remove with Confidence
│ ├─ Remove in small batches, not all at once
│ ├─ One commit per logical group of dead code
│ └─ Keep git history -- you can always recover
Code Smell Detection
Smell
Heuristic
Refactoring
Long function
> 20 lines or > 5 levels of indentation
Extract Function, Decompose Conditional
God object
Class with > 10 methods or > 500 lines
Extract Class, Split by responsibility
Feature envy
Method uses another object's data more than its own
Move Method to the class whose data it uses
Duplicate code
Same logic in 2+ places (> 5 similar lines)
Extract Function, Extract Module
Deep nesting
> 3 levels of if/for/while nesting
Guard Clauses, Early Returns, Extract Function
Primitive obsession
Using strings/numbers where a type would be safer
Value Objects, Branded Types, Enums
Shotgun surgery
One change requires editing 5+ files
Move related code together, Extract Module
Dead code
Unreachable branches, unused exports/imports
Delete it (git has history)
Data clumps
Same group of parameters passed together repeatedly
Extract Parameter Object or Config Object
Long parameter list
Function takes > 4 parameters
Extract Parameter Object, Builder Pattern
Test-Driven Refactoring Methodology
Refactoring Untested Code
│
├─ Step 1: Write Characterization Tests
│ │ Capture CURRENT behavior, even if it seems wrong
│ │ These tests document what the code actually does
│ └─ Goal: safety net, not correctness proof
│
├─ Step 2: Verify Coverage
│ │ Run coverage tool, ensure all paths you will touch are covered
│ └─ Add more tests if coverage is insufficient
│
├─ Step 3: Refactor in Small Steps
│ │ One transformation at a time
│ │ Run tests after EVERY change
│ └─ If tests fail, undo and try smaller step
│
├─ Step 4: Improve Tests
│ │ Now that code is cleaner, write better tests
│ │ Replace characterization tests with intention-revealing tests
│ └─ Add edge cases discovered during refactoring
│
└─ Step 5: Commit and Review
│ Separate commits: tests first, then refactoring
└─ Reviewers can verify tests pass on old code too
Tool Reference
Tool
Language
Use Case
Command
ast-grep
Multi
Structural search and replace
sg -p 'console.log($$$)' -r '' -l js
jscodeshift
JS/TS
Large-scale AST-based codemods
jscodeshift -t transform.js src/
eslint --fix
JS/TS
Auto-fix lint violations
eslint --fix 'src/**/*.ts'
ruff
Python
Fast linting and auto-fix
ruff check --fix src/
goimports
Go
Organize imports
goimports -w .
clippy
Rust
Lint and suggest improvements
cargo clippy --fix
knip
JS/TS
Find unused files, deps, exports
npx knip
ts-prune
TS
Find unused exports
npx ts-prune
vulture
Python
Find dead code
vulture src/ --min-confidence 80
rope
Python
Refactoring library
Python API for rename, extract, move
IDE rename
All
Rename with reference updates
F2 in VS Code, Shift+F6 in JetBrains
sd
All
Find and replace in files
sd 'oldName' 'newName' src/**/*.ts
Common Gotchas
Gotcha
Why It Happens
Prevention
Refactoring and behavior change in same commit
Tempting to "fix while you're in there"
Separate commits: refactor first, then change behavior
Breaking public API during internal refactor
Renamed/moved exports consumed by external code
Re-export from old path, deprecation warnings
Circular dependencies after extracting modules
New module imports from original, original imports from new
Dependency graph check after each extraction
Tests pass but runtime breaks
Tests mock the refactored code, hiding the break
Integration tests alongside unit tests
git history lost after file move
Used cp + rm instead of git mv
Always git mv, verify with git log --follow
Renaming misses string references
IDE rename only catches code references, not configs/docs
rg 'oldName' across entire repo after rename
Over-abstracting (premature DRY)
Extracting after seeing only 2 occurrences
Rule of three: wait for 3 duplicates before extracting
Extracting coupled code
New function has 8 parameters because code is entangled
Refactor coupling first, then extract
Dead code removal breaks reflection/plugins
Dynamic imports, dependency injection, decorators
Grep for string references, check plugin registries
Performance regression after extraction
Extra function calls, lost inlining, cache misses
Benchmark before and after for hot paths
Merge conflicts from large refactoring PR
Long-lived branch diverges from main
Small PRs, merge main frequently, or use stacked PRs
Type errors after moving files
Path aliases, tsconfig paths, barrel exports not updated
Run type checker after every file move
Reference Files
File
Contents
Lines
references/extract-patterns.md
Extract function, component, hook, module, class, configuration -- with before/after examples in multiple languages
~700
references/code-smells.md
Code smell catalog with detection heuristics, tools by language, complexity metrics