Refactor Skill

Overview

Language Agnostic: Examples use Python; port to your project's language.

Core Principles:

• Functionality preserved through tests
• Small, incremental iterations
• All checks must pass before completion

Prerequisites

Before starting refactoring:

1. Tests must exist: If no tests exist for the code, request them first
2. Tests must pass: Verify uv run pytest passes before starting
3. Understand the code: Read and understand what the code does
4. Create a backup: Optionally commit current state before changes

Refactoring Process

Phase 1: Analysis

1. Read the target code thoroughly to understand its purpose
2. Identify code smells - see code-smells.md for detection patterns
3. List refactoring opportunities (wait for user approval before implementing)

Phase 2: TDD Cycle for Each Change

For each discrete refactoring iteration:

🔴 RED (if applicable)

• If adding new simplified behavior, write a failing test first
• If only simplifying existing code, skip to GREEN phase
• Run tests to confirm the new test fails

🟢 GREEN

• Make minimal changes to pass the tests
• Focus on making tests pass, not perfection
• Run uv run pytest after each small change
• Iterate until tests are green

🔵 REFACTOR

• Apply simplification while keeping tests green
• Extract functions, improve naming, reduce complexity
• Continuously run tests after each small change
• Never batch multiple changes - one small step at a time

✅ VERIFY

• Run uv run pytest to ensure all tests pass
• Run uv run ruff check src/ for lint checks
• Run uv run mypy src/ for type checks
• If any check fails, fix and repeat verification

Phase 3: Final Verification

After all refactoring iterations complete:

# Run full CI pipeline until everything passes
bin/ci-local

This runs:

1. Lint checks (ruff)
2. Static type checks (mypy)
3. Tests with coverage (pytest)

Repeat until all checks pass with no errors.

Refactoring Patterns

For common refactoring patterns with before/after examples, see patterns.md.

Includes: Prompt refactoring patterns for code that contains prompts or prompt templates.

Examples

Inline: Extract Function

Before - complex function with embedded calculation:

def generate_report(users, threshold):
    result = []
    for user in users:
        score = user.login_count * 0.3 + user.posts * 0.7
        if score >= threshold:
            result.append({"name": user.name, "score": score})
    return result

After - extracted calculation improves readability and testability:

def calculate_engagement_score(user) -> float:
    return user.login_count * 0.3 + user.posts * 0.7

def generate_report(users, threshold):
    result = []
    for user in users:
        score = calculate_engagement_score(user)
        if score >= threshold:
            result.append({"name": user.name, "score": score})
    return result

Single Iteration Pattern:

1. 🔴 Write test for simplified behavior (if adding new behavior)
2. 🟢 Make minimal changes to pass tests
3. 🔵 Simplify while tests stay green
4. ✅ Run bin/ci-local to verify all checks pass

Repeat for each discrete improvement.