| name | refactor |
| description | Refactors code for quality and maintainability. Triggers: refactor, clean up, restructure, improve code, modernize. |
| user-invocable | true |
| effort | high |
| argument-hint | [target and goal] |
| agent | code-reviewer |
| context | fork |
| allowed-tools | Read, Edit, Grep, Glob, Bash |
Refactor Code
$ARGUMENTS
Plan and execute code refactoring.
Usage
/refactor [target] [--pattern=<pattern>]
What This Command Does
- Analyzes target code
- Identifies refactoring opportunities
- Plans refactoring steps
- Executes with user approval
Refactoring Patterns
| Pattern | Description |
|---|
extract-function | Extract code block to function |
extract-component | Extract UI component |
rename | Rename symbol across codebase |
move | Move code to better location |
inline | Inline unnecessary abstraction |
simplify | Simplify complex logic |
Safety Rules
- Run tests before refactoring
- Make atomic commits
- Preserve behavior (no feature changes)
- Run tests after each step
- Don't mix refactoring with features
Output Format
## Refactoring Plan: [Target]
### Current State
- **Location**: [file:line]
- **Issues**: [what's wrong]
### Proposed Changes
1. [Change 1]
2. [Change 2]
### Impact Analysis
- **Files affected**: [count]
- **Risk level**: [Low/Medium/High]
### Test Coverage
- [x] Unit tests exist
- [ ] Integration tests needed
### Rollback
git revert [commit]
Approval Required
Before executing:
Common Rationalizations
| Excuse | Why It's Wrong |
|---|
| "It works, don't touch it" | Working code that's hard to maintain slows every future change |
| "We'll refactor it later" | Later never comes — refactor when the pain is fresh and context is loaded |
| "It's too risky to change" | That's exactly why it needs refactoring — risk compounds with complexity |
| "Just one more hack won't hurt" | Each hack makes the next one easier to justify — break the cycle now |
| "We need to rewrite from scratch" | Incremental refactoring is safer and delivers value continuously |
READ BEFORE WRITE
This command analyzes and plans first.
Execution requires explicit approval.
MANDATORY: Documentation Update
After refactoring, update documentation:
Required Updates
| Change Type | Update |
|---|
| API changes | API documentation |
| Architecture | architecture note if significant |
| Patterns | Best practices docs |
| Breaking changes | Migration guide |
Post-Refactoring Checklist
Automated Smell Detection
Run the bundled script to find refactoring opportunities:
python3 ${CLAUDE_SKILL_DIR}/scripts/refactor-scan.py src/
Parallel Refactoring (complex cases)
If the scan reports >5 smells across multiple files, use Agent Teams:
Create an agent team for refactoring:
- Teammate 1 (code-reviewer): "Plan the refactoring strategy for [identified smells]. Document what to change and why." Use Opus. READ-ONLY.
- Teammate 2 (backend-specialist): "Implement the refactoring changes identified by the reviewer." Use Opus.
Teammate 1 completes first, then Teammate 2 acts on the plan.
Related Skills
- Need a safe refactor plan? →
/refactor-plan for incremental steps as GitHub RFC
- Want to validate architecture? →
/analyze for code quality metrics
- Need tests before refactoring? →
/tdd to build safety net first
- Architecture decision needed? →
/council for multi-perspective evaluation
Rules
- MUST run the full test suite before starting — a green baseline is the only way to tell the refactor did not break anything
- MUST preserve behavior end-to-end; if behavior must change, stop and ask — "while we're here" changes are how refactors introduce bugs
- NEVER mix refactoring with feature changes in the same commit — they fail review and rollback differently
- NEVER refactor untested code without adding tests first — the refactor has nothing to assert against
- CRITICAL: commits stay small and individually reversible. A 2000-line refactor commit cannot be code-reviewed and cannot be bisected.
- MANDATORY: dead-code cleanup is part of the refactor per Constitution Art. VI.1 — orphaned references left behind from a refactor are a quality regression, not "later work"
Gotchas
- "Behavior-preserving" refactors still change observable things: timing, memory allocation, error message text, log line format. Downstream consumers may rely on these — scan for log parsers or monitoring rules before changing prose in exceptions.
- IDE rename refactors miss dynamic references (string-keyed dicts, reflection,
getattr, dynamic imports). After a rename, grep for the old name in strings and comments — the IDE will not.
- Git history diffing is confused by combined move + content changes. Split moves into their own commit (
git mv + tiny commit) so later reviewers can use git log --follow.
- Preserving backward compatibility is a spectrum. "Keep the old function as a thin wrapper" sounds safe but often defers the cleanup forever — prefer deprecate-with-warning followed by a scheduled removal.
- Refactor-to-DRY abstractions made from 2 use cases often need to be torn down when the 3rd use case arrives (Rule of Three). Resist abstracting until the third repetition makes the shape obvious.
- Test suites that rely on mocks frequently pass during refactors that silently break real behavior (the mock reflects the old shape). Run integration tests, not just unit, before marking done.
When NOT to Use
- For planning a refactor (no execution) — use
/refactor-plan
- For architectural audit of shallow modules — use
/architecture-audit
- For fixing a specific bug — use
/fix or /debug
- For adding a feature — use
/plan then the relevant language skill
- When tests do not exist or are red — write tests first (
/tdd) before refactoring
