Refactor Session

Change structure, not behavior. If behavior changes, that's a feature or fix — not a refactor.

Hard rule: Never refactor and change behavior in the same commit. Pick one.

Think Before Refactoring

Before jumping into structural changes:

1. What is the END STATE you want? Describe the ideal structure, not just "clean up this mess."
2. Are there multiple valid end states? Which serves the project best long-term?
3. Is this the right time? Does this refactor block other work, or is it investment for the future?

Don't start moving code until you can describe where everything should end up.

Rule of Three before abstraction: Count concrete use cases RIGHT NOW (not hypothetical). If < 3, write the concrete version. Three similar lines of code is better than one premature abstraction. Only extract when you have 3+ real instances.

Before Starting: Get a Safety Net

1. Write characterization tests — capture what the code currently does
2. Run tests — they must pass before you start
3. Commit the tests: test: add characterization tests for <module>

Now any breakage is immediately visible.

Refactor Types

The Process: One Change Per Commit

1. Make ONE structural change
2. Run tests — must still pass
3. Commit: "refactor: <what changed>"
4. Repeat

Never batch multiple refactors. One change = one commit = easy to revert if needed.

Guard Clauses: Flatten Deep Nesting

# BEFORE: hard to read with deep nesting
def process(data):
    if data:
        if data.is_valid():
            if not data.is_processed:
                do_work(data)

# AFTER: guard clauses (same behavior, flat structure)
def process(data):
    if not data:
        return
    if not data.is_valid():
        return
    if data.is_processed:
        return
    do_work(data)

Rename Safely

Rename one thing at a time. After renaming, verify all usages updated:

grep -r "old_name" .    # find any remaining references

Fix every usage before committing. IDE refactor tools are safer than manual find-replace.

When to STOP

Stop immediately if:

• You find a bug → fix it in a separate fix: commit, then resume
• You want to add a feature → do it in a separate feat: commit
• Tests start failing and you're not sure why → git diff to see what changed, revert the last step
• The refactor keeps growing → stop, open a TODO, scope it properly first

Quick Reference

Out of Scope

• NOT for fixing bugs or changing behavior — use a debug skill for bugs, a TDD skill for new behavior
• NOT for adding new features while restructuring — use a spec-driven-development skill for feature work
• NEVER use this for full rewrites or redesigns — if the refactor feels like a rewrite, scope it as a new feature instead
• NOT for code review of someone else's work — use a code-review skill instead

Common Traps

• Refactoring without tests: Run existing tests first to establish baseline — without a green test suite, you can't tell if your refactor broke behavior.
• Scope creep during refactoring ("while I'm here..."): Stick to the stated refactoring goal — mixing refactoring with feature work or unrelated cleanup creates hard-to-review commits and increases revert risk.
• Breaking public API contracts: Check for callers before renaming/removing — grep for all usages of any function, class, or method you're changing. External consumers won't get your rename for free.