refactoring-code

Refactoring Code

Core principle: Refactoring changes structure, not functionality. If behavior changes, you're rewriting.

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

1. Make one change at a time
2. Run tests after each change
3. Check TypeScript compilation
4. Verify behavior unchanged

If something breaks: STOP. Use Skill(ce:systematic-debugging). Don't proceed until understood.