refactor

name	refactor
description	Safe refactoring with comprehensive test coverage
argument-hint	<what-to-refactor>

Safe Refactoring

Refactor code safely with tests as a safety net.

RULE: All tests must pass before AND after. No behavior changes.

Arguments

• $ARGUMENTS - What to refactor (file, module, pattern, etc.)

Phase 0: Preparation

0.1 Parallel Discovery

Launch three agents in parallel to gather all baseline information simultaneously:

Agent A: Coverage Report

Task: Generate the test coverage report for the affected area.
Run `./gradlew koverReport` and read the coverage output.
Report the coverage percentage for every file in the refactoring scope.
Flag any file below 80% coverage.

Agent B: Baseline Tests

Task: Run the full test suite and report results.
Run `./gradlew test`.
Report pass/fail counts and list any failures with their full stack traces.

Agent C: Scope Analysis

Task: Analyze the refactoring scope for `$ARGUMENTS`.
Determine what is being refactored: single file, multiple related files, entire module, or cross-cutting pattern.
Identify and list:
- Every public API surface (public functions, classes, interfaces, data classes)
- Expected inputs and outputs for each public entry point
- Edge cases and error paths
- Integration points with other modules
- All direct dependents (files that import or reference the target)
Write findings to `.claude/plans/PLAN-refactor-scope.md`.

Wait for all three agents to complete before continuing.

0.2 Evaluate Results

Review the outputs from all three agents:

• If Agent B reported test failures: STOP. Fix failures before proceeding.
• If Agent A reported coverage below 80% for any file in scope: proceed to Phase 1.
• If coverage is adequate (>=80%): skip Phase 1, proceed to Phase 2.

Phase 1: Add Missing Tests

1.1 Parallel Gap Analysis

Launch parallel agents per dimension to identify every untested path. Create one agent per category:

Agent: Branch Coverage

Task: Analyze the coverage report and source code for `$ARGUMENTS`.
List every uncovered branch (if/else, when, try/catch) with file path and line numbers.
For each uncovered branch, write a one-line description of what condition triggers it.

Agent: Edge Cases

Task: Analyze the source code for `$ARGUMENTS`.
List every edge case that lacks a test: null inputs, empty collections, boundary values,
overflow conditions, concurrent access, and type coercion scenarios.
For each, specify the function and the exact edge condition.

Agent: Error Paths

Task: Analyze the source code for `$ARGUMENTS`.
List every error/exception path that lacks a test: thrown exceptions, error returns,
fallback branches, retry logic, timeout handling, and resource cleanup paths.
For each, specify the function, the error condition, and expected behavior.

Wait for all agents to complete. Merge their findings into a single prioritized list.

1.2 Write Characterization Tests

Tests that capture CURRENT behavior (even if it seems wrong):

• Test what the code DOES, not what it SHOULD do
• These tests lock in behavior during refactoring
• Work through the merged list from 1.1, highest-priority gaps first

# Verify new tests pass
./gradlew test

STOP IF TESTS FAIL. Fix tests until green.

Phase 2: Plan Refactoring

Launch a planner agent (subagent_type: "planner") with the scope analysis from Phase 0 and the refactoring request. The planner will:

• Rank refactoring goals by impact (readability, performance, maintainability, duplication, abstractions)
• Identify which standard refactoring patterns apply with exact file/line locations
• Break the refactoring into small, safe steps — each independently committable and test-green
• Identify which steps are independent (can run in parallel worktrees) vs sequential
• Order renames and moves before structural changes

Then launch a verifier agent (subagent_type: "verifier") to validate the plan. Iterate until APPROVED.

Phase 3: Execute Refactoring

Independent steps (touching different files with no dependency): launch ALL simultaneously as worktree-isolated architect agents, then merge via the consolidator.

Sequential steps (each depends on the previous): execute one at a time:

For each step:

3.1 Make One Change

Single, focused change:

• Rename
• Extract method/class
• Move code
• Simplify logic
• Remove duplication

3.2 Run Tests

./gradlew test

STOP IF TESTS FAIL. Fix or revert before continuing.

3.3 Commit

Delegate to the skills:commit command:

Skill(skill="skills:commit", args="(refactor): [specific change made]")

3.4 Repeat

Continue with next step until refactoring complete.

Phase 4: Review

Launch a reviewer agent (subagent_type: "reviewer") to review the full diff (git diff main...HEAD). Focus: behavior preservation, no accidental API changes, code quality improvement. Fix any critical/major issues found.

Phase 5: Final Verification

Launch a verifier agent (subagent_type: "verifier") in post-verification mode. It confirms: tests pass (count not decreased from baseline), lint clean, build succeeds, no behavior changes, all public APIs preserved.

Common Refactoring Patterns

Extract Method

// Before
fun process() {
    // 20 lines of validation
    // 20 lines of processing
}

// After
fun process() {
    validate()
    doProcessing()
}

Extract Class

When a class has too many responsibilities.

Rename for Clarity

When names don't reflect purpose.

Remove Duplication

Extract shared logic to helper/utility.

Simplify Conditionals

Replace complex if/else with when, early returns, or polymorphism.

Replace Magic Values

Extract constants with meaningful names.

Completion Criteria

• Adequate test coverage before starting
• All tests pass after each step
• Refactoring improves code quality
• No behavior changes
• Code reviewed
• Final tests pass
• Committed with clear messages