Refactor

Refactoring Skill

Structured workflow for identifying refactoring opportunities, assessing impact, and executing safe refactors that preserve behavior. Produces a refactoring plan with before/after examples and generates task files for large refactors.

Workflow

Step 1: Identify Refactoring Opportunities

Scan the codebase for common refactoring signals:

For each opportunity found, record:

• File and line range: Exact location
• Category: Which signal it matches
• Severity: High (blocks new features), Medium (increases maintenance cost), Low (cosmetic)
• Estimated effort: Small (< 1 hour), Medium (1-4 hours), Large (> 4 hours)

Output: Refactoring opportunity inventory sorted by severity then effort.

Step 2: Impact Analysis

For each candidate refactoring, assess:

1. Blast radius: How many files/packages are affected?
2. Test coverage: Are the affected areas well-tested? Check coverage reports.
3. Active development: Is anyone currently working on these files? Check recent git history.
4. Risk level: Could this break existing behavior?

Impact Matrix:
| Refactoring | Files Affected | Test Coverage | Risk | Priority |
|-------------|---------------|---------------|------|----------|
| Extract X   | 3             | 85%           | Low  | High     |
| Rename Y    | 12            | 40%           | Med  | Medium   |

Rules:

• Never refactor code with < 50% test coverage without adding tests first
• Never refactor during active incident response
• Prefer small, focused refactors over large sweeping changes

Step 3: Create Refactoring Plan

For each approved refactoring, document:

## Refactoring: {Description}

### Motivation
Why this refactoring is needed (not just "code is messy" -- concrete impact on development).

### Before
{Actual code snippet showing the current state}

### After
{Code snippet showing the target state}

### Steps
1. {Concrete step with file paths}
2. {Next step}
3. ...

### Behavior Preservation
- [ ] All existing tests pass before starting
- [ ] No test modifications needed (tests validate behavior, not implementation)
- [ ] All existing tests pass after refactoring
- [ ] No new warnings or lint errors introduced

### Rollback
If the refactoring introduces issues: `git revert {commit}`. Each refactoring is a single commit.

Present the plan to the user for approval before proceeding.

Step 4: Execute Refactoring

For each approved refactoring item:

1. Verify tests pass before starting: Run the full quality gates
2. Make the change in a single, focused commit
3. Run tests after each change -- stop immediately if anything fails
4. Run linters to catch any regressions
5. Verify behavior preservation: Compare test results before and after

Rules:

• One refactoring per commit -- never mix refactorings
• Never change behavior -- if a test needs to change, that's a behavior change, not a refactoring
• Leave the code better than you found it -- but only within the defined scope

Step 5: Generate Task Files for Large Refactors

If a refactoring is too large for a single session (Large effort, >10 files affected):

1. Break it into independent, sequentially-executable chunks
2. Create task files in docs/spec/.llm/tasks/backlog/ using the task template
3. Set ## Dependencies: to enforce ordering where needed
4. Each task should be independently verifiable (tests pass after each task)
5. Update docs/spec/.llm/STRATEGY.md with the refactoring plan

Step 6: Update Knowledge Base

After completing refactoring:

1. Update docs/spec/.llm/PROGRESS.md with:
   • Patterns discovered or established
   • Decisions made and rationale
   • Any issues encountered
2. If the refactoring establishes a new pattern, consider adding or updating a rule in .claude/rules/

Common Refactoring Patterns

Anti-Patterns

Arguments

$ARGUMENTS

Converted and distributed by TomeVault — claim your Tome and manage your conversions.