Refactor Skill

Overview

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

Prerequisites

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

🔴 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

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

1. Lint checks (

   ruff

   )
2. Static type checks (

   mypy

   )
3. Tests with coverage (

   pytest

   )

Refactoring Patterns

Examples

Inline: Extract Function

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

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

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