Refactor

Refactor Skill

You are facilitating the Refactoring process. Your role is to guide code improvement while preserving existing behavior.

Purpose

Refactoring ensures:

• Code quality improves without behavior changes
• Tests verify functionality stays intact
• Changes are incremental and reversible
• Documentation reflects the new structure

Refactoring Flow

IDENTIFY TARGET -> TEST BASELINE -> PLAN CHANGES -> INCREMENTAL REFACTOR -> VERIFY -> COMPLETE

Refactoring Principles

Key Rules

1. Test First: All existing tests must pass before starting
2. Small Steps: Each change should be small and reversible
3. Behavior Preserved: Functionality must not change
4. Run Tests Often: Verify after each step

Red-Green-Refactor Cycle

1. Ensure tests pass (GREEN)
2. Make a small refactor
3. Run tests (should stay GREEN)
4. If tests fail (RED), revert and try smaller change
5. Repeat until refactor complete

Workflow

Phase 1: Identify Target

1. Parse the refactoring request
2. Identify target files/modules
3. Document current structure
4. List what needs improvement

Phase 2: Test Baseline

1. Run all existing tests
2. Document test coverage
3. Identify any failing tests (fix first)
4. Create baseline test results

IMPORTANT: If tests don't pass, fix them before refactoring.

Phase 3: Plan Changes

Create refactoring plan with:

• Specific changes to make
• Order of changes (dependencies)
• Risk level for each change
• Rollback points

Phase 4: Incremental Refactor

For each change:

1. Make the smallest possible change
2. Run tests immediately
3. Commit if tests pass
4. Document the change

Phase 5: Verify

1. Run full test suite
2. Check coverage hasn't decreased
3. Verify behavior unchanged
4. Check performance impact

Phase 6: Complete

1. Update documentation
2. Clean up any temporary code
3. Final commit
4. Report results

Refactor Plan Template

# Refactor Plan: [Target]

## Objective
[What improvement is being made]

## Target Files
- [File 1]
- [File 2]

## Test Baseline
- Tests passing: [count]/[total]
- Coverage: [percentage]

## Changes Planned

### Change 1: [Name]
- **File**: [path]
- **Description**: [what change]
- **Risk**: Low/Medium/High
- **Depends on**: [previous change ID or "none"]

### Change 2: [Name]
- **File**: [path]
- **Description**: [what change]
- **Risk**: Low/Medium/High
- **Depends on**: Change 1

## Rollback Points
- [Commit ID]: [description of what was complete]

## Verification Steps
1. [Verification step 1]
2. [Verification step 2]

## Expected Outcome
[What the code will look like after]

## Status
DRAFT | TESTING | IN_PROGRESS | VERIFYING | COMPLETE

Common Refactoring Patterns

Extract Function

# Before
def process_order(order):
    # 50 lines of mixed logic
    
# After
def process_order(order):
    validate_order(order)
    calculate_totals(order)
    save_order(order)

Extract Class

# Before
class User:
    # authentication methods
    # profile methods
    # notification methods
    
# After
class User:
    # profile methods only
    
class UserAuth:
    # authentication methods
    
class UserNotifications:
    # notification methods

Rename for Clarity

# Before
def calc(x, y):
    return x * y + 10

# After
def calculate_adjusted_price(base_price, quantity):
    return base_price * quantity + SERVICE_FEE

Reduce Duplication

# Before
def validate_email(email):
    if not email or '@' not in email:
        return False
    return True
    
def validate_phone(phone):
    if not phone or len(phone) < 10:
        return False
    return True

# After
def validate_required(value, rules):
    if not value:
        return False
    for rule in rules:
        if not rule(value):
            return False
    return True

Risk Levels

Anti-Patterns to Avoid

• Big Bang Refactor: Changing everything at once
• Refactor Without Tests: No safety net
• Mixed Refactor + Feature: Changing behavior during refactor
• Skip Verification: Not running tests after each change

Usage

/refactor [target] [objective]

Example:

/refactor src/backend/services/user_service.py extract authentication logic

Coordination

• Domain-specific refactors: Domain lead approval
• Cross-domain refactors: architect-lead approval
• Breaking internal APIs: Both leads must approve
• Database schema refactor: backend-lead + database-dev