Refactoring Code Skill | Agent Skills

Refactoring Code

You are following a systematic refactoring methodology that improves code quality, maintainability, and simplicity while preserving existing behavior.

Core Principle: Refactoring changes structure, not functionality. Safety and clarity are more important than elegance.

The Iron Law

BEHAVIOR MUST BE PRESERVED
Tests must verify behavior, not implementation

If you change what the code does (not just how it does it), you're not refactoring—you're rewriting.

Prerequisites

Access to codebase for pattern research
Behavior-driven tests that verify current functionality
Understanding of project conventions

Core Responsibilities

Simplify Complex Code - Break down complex functions, reduce nesting, improve readability
Extract Patterns - Identify and extract reusable components, hooks, utilities
Eliminate Duplication - Apply DRY principles while avoiding premature abstraction
Improve Type Safety - Strengthen TypeScript usage, eliminate any types when possible
Performance Optimization - Identify unnecessary re-renders, optimize data structures
Align with Standards - Ensure code follows project patterns and conventions

The Five-Phase Refactoring Process

You MUST complete each phase before proceeding to the next.

Copy this checklist and track your progress:

Refactoring Progress:
- [ ] Phase 1: Understand Current Behavior
  - [ ] Read existing code thoroughly
  - [ ] Check usage across codebase
  - [ ] Document current behavior
- [ ] Phase 2: Verify Test Coverage (CRITICAL)
  - [ ] Behavior-driven tests exist and pass
  - [ ] Tests cover main workflows and edge cases
  - [ ] Tests don't depend on implementation details
- [ ] Phase 3: Identify Issues
  - [ ] Issues documented with locations
  - [ ] Issues categorized by type and severity
  - [ ] Root cause understood for each issue
- [ ] Phase 4: Plan Refactoring
  - [ ] Broken into small, verifiable steps
  - [ ] Each step has verification criteria
  - [ ] Dependencies between steps identified
- [ ] Phase 5: Execute & Verify
  - [ ] All planned changes implemented
  - [ ] All tests pass
  - [ ] No new type errors or warnings
  - [ ] Behavior verified unchanged

Phase 1: Understand Current Behavior

Objective: Know exactly what the code does before changing how it does it.

Read existing code thoroughly
- Understand the purpose, not just the implementation
- Identify inputs, outputs, and side effects
- Note any edge cases or error handling
Check usage across codebase
- Use Grep to find all call sites
- Understand how consumers depend on this code
- Identify any public APIs that must remain stable
Document current behavior
- List what the code accomplishes
- Note any implicit contracts or assumptions
- Identify performance characteristics if relevant

Phase 1 Complete When:

[ ] You can explain what the code does in plain language
[ ] All call sites and dependencies are identified
[ ] Current behavior is documented

Phase 2: Verify Test Coverage (CRITICAL)

Objective: Ensure behavior-driven tests exist that will catch regressions.

BEFORE refactoring, ensure tests verify BEHAVIOR (what users see/do), NOT implementation:

✅ Good - Behavior-driven tests:

// Tests user-observable behavior
test('displays error message when API returns 404', async () => {
  server.use(
    http.get('/api/users', () => new HttpResponse(null, { status: 404 }))
  );
  render(<UserList />);
  expect(await screen.findByText(/user not found/i)).toBeInTheDocument();
});

❌ Bad - Implementation-detail tests:

// Tests internal state/functions - breaks during refactoring
test('sets error state when fetch fails', () => {
  const wrapper = shallow(<UserList />);
  wrapper.instance().handleError(new Error('404'));
  expect(wrapper.state('error')).toBe('404');
});

Test Quality Checklist:

[ ] Tests verify user workflows, not function calls
[ ] Tests use real dependencies (not mocks of components)
[ ] Tests query by role/label/text, not internal state
[ ] Tests will survive refactoring when behavior unchanged

If tests are missing or test implementation details:

Add behavior-driven tests first (see writing-tests skill)
Focus on user workflows, loading/error states, interactions
Ensure new tests are passing before refactoring

Why this matters: Unit tests checking internal state break during refactoring even when behavior is unchanged. Behavior-driven tests prove the feature works before and after.

Phase 2 Complete When:

[ ] Behavior-driven tests exist and pass
[ ] Tests cover main workflows and edge cases
[ ] Tests don't depend on implementation details

Phase 3: Identify Issues

Objective: Systematically catalog what needs improvement.

Common refactoring opportunities:

| Issue Type | Indicators | Impact | |------------|-----------|---------| | Complexity | Deep nesting (>3 levels), long functions (>50 lines), many parameters (>4) | Hard to understand, error-prone | | Duplication | Copy-pasted code, repeated patterns, similar logic in multiple places | Maintenance burden, inconsistent fixes | | Poor Naming | Unclear variables (x, data, temp), misleading names, inconsistent terminology | Cognitive overhead | | Type Safety Gaps | any types, missing types, type assertions, implicit any | Runtime errors, poor IDE support | | Performance Issues | Unnecessary re-renders, inefficient algorithms (O(n²) when O(n) possible), large bundle size | Slow UX, high resource usage | | Pattern Violations | Inconsistent with project conventions, outdated patterns | Team confusion, tech debt |

Analysis checklist:

[ ] Identify specific complexity hotspots
[ ] Catalog duplicated code blocks
[ ] List unclear or misleading names
[ ] Find type safety vulnerabilities
[ ] Measure performance bottlenecks (if applicable)
[ ] Check against project conventions

Phase 3 Complete When:

[ ] All issues are documented with locations
[ ] Issues are categorized by type and severity
[ ] You understand the root cause of each issue

Phase 4: Plan Refactoring

Objective: Create a safe, incremental execution plan.

Create todo list for multi-step refactorings (use TodoWrite tool)
- Break large refactorings into small, verifiable steps
- Each step should be independently testable
Prioritize changes by impact and risk
- High impact, low risk first (e.g., rename variables)
- Defer high-risk changes (e.g., algorithm rewrites)
Consider backward compatibility
- If this is a public API, can we deprecate gradually?
- Do we need to support both old and new interfaces temporarily?
Plan verification steps
- What will you check after each change?
- Which tests must pass?

Example refactoring breakdown:

**Large task:** Extract user authentication logic into reusable hook

**Breakdown:**
1. Create new hook file with basic structure
2. Move authentication state management to hook
3. Move login/logout handlers to hook
4. Extract token refresh logic
5. Replace inline logic in components with hook calls
6. Remove old duplicated code
7. Add tests for hook

Phase 4 Complete When:

[ ] Refactoring is broken into small steps
[ ] Each step has clear verification criteria
[ ] Dependencies between steps are identified
[ ] Risk mitigation strategies are planned

Phase 5: Execute & Verify

Objective: Make changes safely with continuous verification.

Execution principles:

Make one change at a time
- Single responsibility per edit
- Commit frequently if using git
Run tests after each change
- Don't accumulate untested changes
- Catch regressions immediately
Check TypeScript compilation
- tsc --noEmit or equivalent
- Fix type errors before proceeding
Verify behavior unchanged
- Run the application manually if needed
- Confirm user-facing behavior is identical

Verification checklist per step:

[ ] Tests pass (npm test or equivalent)
[ ] TypeScript compiles without errors
[ ] No new linting warnings
[ ] Behavior manually verified (if high-risk change)

If something breaks:

STOP immediately
Use systematic-debugging skill to investigate
Don't proceed until root cause is understood
Consider reverting if fix is unclear

Phase 5 Complete When:

[ ] All planned changes are implemented
[ ] All tests pass
[ ] No new type errors or warnings
[ ] Code follows project conventions
[ ] Behavior is verified unchanged

Red Flags - STOP and Reassess

If you catch yourself:

Changing behavior while refactoring → You're rewriting, not refactoring. Separate behavior changes from refactoring.
"I'll just skip the tests this time" → Tests are your safety net. No tests = no safe refactoring.
Adding complexity to remove complexity → Over-engineering. Simpler solution probably exists.
"This is clever!" → Code should be clear, not clever. Clever code is hard to maintain.
Removing comments that explained context → Comments explaining "why" are valuable. Keep them.
Breaking existing APIs without considering consumers → Check all call sites. Plan deprecation if needed.
Abstracting before seeing pattern 3 times → Rule of Three: Don't abstract until you see the pattern repeated three times.

ALL of these mean: STOP. Reassess your approach.

React/TypeScript Patterns

For TypeScript/React projects, see references/react-typescript.md for component structure, type safety patterns, and refactoring checklists.

Common Refactoring Patterns - Quick Reference

| Smell | Refactoring | Example | |-------|-------------|---------| | Long function | Extract smaller functions | Split 100-line function into 5 focused functions | | Duplicate code | Extract to shared utility | Create formatCurrency() instead of inline formatting | | Deep nesting | Early returns, guard clauses | Replace if/else pyramid with early returns | | Magic numbers | Named constants | const MAX_RETRIES = 3 instead of hardcoded 3 | | Large component | Split into smaller components | Extract <UserProfile> from <Dashboard> | | Complex condition | Extract to named function | isEligibleForDiscount() instead of if (user.age > 65 && user.isPremium && ...) | | Primitive obsession | Create type/interface | type Email = string with validation instead of raw strings | | Long parameter list | Parameter object | Pass { user, options, config } instead of 8 parameters |

Integration with Other Skills

This skill requires using:

writing-tests - REQUIRED when adding behavior-driven tests before refactoring
systematic-debugging - REQUIRED when refactoring breaks tests unexpectedly

Complementary skills:

verification-before-completion - Use before claiming refactoring is complete
testing-anti-patterns - Avoid when writing tests for refactored code

When to Stop Refactoring

You've refactored enough when:

✅ Code is clear and easy to understand
✅ Duplication is eliminated (without over-abstraction)
✅ Types are explicit and safe
✅ Tests pass and coverage is maintained
✅ Code follows project conventions
✅ Team members can understand the code without explanation

Don't refactor further if:

You're making code "elegant" but harder to understand
You're abstracting before seeing the pattern 3 times
You're refactoring code that works well and won't change soon
You're optimizing performance without measuring first

Communication

When proposing refactorings:

Explain what problems you're solving
- "This function is 150 lines and does 5 different things"
- Not just "This code could be better"
Show before/after comparisons
- Demonstrate the improvement concretely
- Highlight reduced complexity metrics
Highlight risks and breaking changes
- "This changes the public API"
- "Consumers will need to update imports"
Suggest incremental steps for large refactorings
- "We can do this in 3 phases over 2 weeks"
- Make large changes less scary
Challenge your own assumptions
- "Is this really better, or just different?"
- "Am I solving a real problem?"

Key Principles Summary

Preserve behavior - Tests must verify same outcomes before and after
Test first - Behavior-driven tests are your safety net
Small steps - One change at a time, verify continuously
Clarity over cleverness - Code should be obvious, not impressive
Rule of Three - Don't abstract until you see the pattern three times
Safety over elegance - Working code is better than beautiful code

Remember: The goal of refactoring is to make future changes easier, not to make code perfect.

Agent Skills: Refactoring Code

Install this agent skill to your local

Skill Files