SKILL.md

/refactor - Refactoring Workflow

Safe refactoring with review gates.

When to Use

"Refactor X"

"Clean up this code"

"Extract this into a module"

"Improve the architecture of Y"

Large-scale code restructuring

Technical debt reduction

Workflow Overview

┌──────────┐    ┌────────────┐    ┌──────────┐    ┌──────────┐    ┌───────────┐

│ phoenix  │───▶│   plan-    │───▶│  kraken  │───▶│plan-reviewer│───▶│ arbiter  │

│          │    │   agent    │    │          │    │          │    │           │

└──────────┘    └────────────┘    └──────────┘    └──────────┘    └───────────┘

  Analyze         Plan             Implement       Review          Verify

  current         changes          refactor        changes         tests pass

Agent Sequence

Agent

Role

Output

phoenix

Analyze current code, identify improvement areas

Analysis report

plan-agent

Create safe refactoring plan

Step-by-step plan

kraken

Implement the refactoring

Code changes

plan-reviewer

Review changes for correctness

Review report

arbiter

Verify all tests still pass

Test report

Refactoring Principles

Tests first: Ensure adequate test coverage before refactoring

Small steps: Each change should be independently verifiable

Behavior preserved: No functional changes during refactor

Reviewable: Changes should be easy to review

Execution

Phase 1: Analyze

Task(

  subagent_type="phoenix",

  prompt="""

  Analyze for refactoring: [TARGET_CODE]

  Identify:

  - Current pain points

  - Code smells

  - Improvement opportunities

  - Risk areas

  - Test coverage gaps

  """

)

Phase 2: Plan

Task(

  subagent_type="plan-agent",

  prompt="""

  Plan refactoring: [TARGET_CODE]

  Analysis: [from phoenix]

  Create:

  - Step-by-step refactoring plan

  - Each step should be:

    - Small and focused

    - Independently testable

    - Reversible

  - Identify files affected

  - Risk mitigation strategy

  """

)

Phase 3: Implement

Task(

  subagent_type="kraken",

  prompt="""

  Implement refactoring: [TARGET_CODE]

  Plan: [from plan-agent]

  Requirements:

  - Follow plan exactly

  - Run tests after each step

  - Stop if tests fail

  - NO behavior changes

  """

)

Phase 4: Review

Task(

  subagent_type="plan-reviewer",

  prompt="""

  Review refactoring: [TARGET_CODE]

  Changes: [git diff from kraken]

  Check:

  - Behavior preserved

  - No unintended changes

  - Code quality improved

  - Patterns consistent

  """

)

Phase 5: Validate

Task(

  subagent_type="arbiter",

  prompt="""

  Validate refactoring: [TARGET_CODE]

  - Run full test suite

  - Verify no regressions

  - Check type errors

  - Run linting

  """

)

Refactoring Types

Extract Module

phoenix → plan-agent → kraken → plan-reviewer → arbiter

Rename/Restructure

phoenix → kraken → arbiter  (simpler, skip detailed planning)

Architecture Change

phoenix → plan-agent → [kraken → plan-reviewer] × N phases → arbiter

Example

User: /refactor Extract the validation logic into a separate module

Claude: Starting /refactor workflow...

Phase 1: Analyzing current structure...

[Spawns phoenix]

Found: Validation logic spread across 4 files

- form.ts (lines 45-120)

- api.ts (lines 200-280)

- user.ts (lines 15-45)

- order.ts (lines 88-130)

Phase 2: Planning extraction...

[Spawns plan-agent]

Plan:

1. Create src/validation/index.ts

2. Extract common validators

3. Update imports one file at a time

4. Run tests after each change

Phase 3: Implementing...

[Spawns kraken]

Completed all 4 steps, tests green after each

Phase 4: Reviewing changes...

[Spawns plan-reviewer]

✅ All behavior preserved

✅ DRY improved (removed 45 duplicate lines)

✅ New structure consistent

Phase 5: Final validation...

[Spawns arbiter]

✅ 312 tests passing, 0 regressions

Refactoring complete!

Safety Flags

--dry-run: Plan but don't implement

--step-by-step: Pause after each change for approval

--coverage-check: Require >80% coverage before proceeding

refactor