---
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

1. **Analyzes** target code
2. **Identifies** refactoring opportunities
3. **Plans** refactoring steps
4. **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

```markdown
## 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:
- [ ] Plan reviewed
- [ ] Tests passing
- [ ] Backup created

## 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
- [ ] Tests still pass
- [ ] No behavior changes
- [ ] **Documentation updated if interfaces changed**
- [ ] Code comments updated

## Automated Smell Detection

Run the bundled script to find refactoring opportunities:

```bash
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