Refactoring Code
Core principle: Refactoring changes structure, not functionality. If behavior changes, you're rewriting.
Target: If $ARGUMENTS is provided, use it as the refactoring target. Otherwise, check for unstaged changes. If none, diff against main: git diff --name-only $([ "$(git rev-parse --abbrev-ref HEAD)" = "main" ] && echo "HEAD^" || echo "main...HEAD")
The Five Phases
Refactoring Progress:
- [ ] Phase 1: Understand current behavior
- [ ] Phase 2: Verify behavior-driven tests exist
- [ ] Phase 3: Identify issues
- [ ] Phase 4: Plan incremental steps
- [ ] Phase 5: Execute with continuous verification
Phase 1: Understand Current Behavior
- Read code to understand purpose, not just implementation
- Use Grep to find all call sites and consumers
- Document inputs, outputs, side effects, edge cases
Phase 2: Verify Test Coverage (CRITICAL)
Tests must verify BEHAVIOR, not implementation:
// ✅ Behavior-driven - survives refactoring
test('displays error when API returns 404', async () => {
server.use(http.get('/api/users', () => new HttpResponse(null, { status: 404 })));
render(<UserList />);
expect(await screen.findByText(/not found/i)).toBeInTheDocument();
});
// ❌ Implementation-detail - breaks during refactoring
test('sets error state', () => {
wrapper.instance().handleError(new Error('404'));
expect(wrapper.state('error')).toBe('404');
});
If tests are missing: Add behavior-driven tests first using Skill(ce:writing-tests).
Phase 3: Identify Issues
| Issue | Indicators | Fix |
|---|---|---|
| Complexity | Deep nesting, >50 line functions | Extract smaller functions |
| Duplication | Copy-pasted code | Extract shared utility |
| Poor naming | x, data, temp |
Rename to intent |
| Type gaps | any types, assertions |
Add proper types |
Phase 4: Plan Refactoring
- Break into small, independently testable steps
- High impact + low risk first (e.g., renames)
- Defer high-risk changes (algorithm rewrites)
Phase 5: Execute & Verify
- Make one change at a time
- Run tests after each change
- Check TypeScript compilation
- Verify behavior unchanged
If something breaks: STOP. Use Skill(ce:systematic-debugging). Don't proceed until understood.
Red Flags - STOP and Reassess
- Changing behavior while refactoring (separate concerns)
- Skipping tests ("just this once")
- Adding complexity to remove complexity
- "This is clever!" (clarity > cleverness)
- Abstracting before seeing pattern 3 times
Quick Reference
| Smell | Refactoring |
|---|---|
| Long function | Extract smaller functions |
| Duplicate code | Extract to shared utility |
| Deep nesting | Early returns, guard clauses |
| Magic numbers | Named constants |
| Large component | Split into smaller components |
| Long parameter list | Parameter object |
When to Stop
Stop when code is clear, duplication eliminated, types explicit, tests pass.
Don't continue if:
- Making code "elegant" but harder to understand
- Abstracting before 3 occurrences
- Optimizing without measuring
For React/TypeScript patterns, see references/react-typescript.md.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.