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

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.

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

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.