Refactor

Refactor Workflow Skill

Overview

Two-track workflow for improving existing code. Polish track for small, contained refactors; overhaul track for architectural changes and migrations. Both tracks emphasize exploration before commitment and mandatory documentation updates.

Triggers

Activate this skill when:

• User runs refactor command
• User wants to improve existing code structure
• User mentions "refactor", "restructure", "clean up", "migrate"
• User asks to "move", "extract", "rename", or "reorganize" code

Disambiguation: If the user says "fix" or "clean up" — use refactor when the code works but needs structural improvement. Use debug when something is broken (error, crash, wrong behavior).

Workflow Overview

                              refactor
                                  |
                            +-----+-----+
                            |  Explore  |
                            +-----+-----+
                                  |
                   +--------------+--------------+
                   |                             |
              --polish                       (default)
                   |                             |
                   v                             v
          +--------------+              +--------------+
          |    Polish    |              |   Overhaul   |
          |    Track     |              |    Track     |
          +--------------+              +--------------+

Command Interface

Start Refactor Workflow

# Default: overhaul track
refactor "Description of what needs refactoring"

# Fast path: polish track
refactor --polish "Small contained refactor description"

# Explore first, then decide track
refactor --explore "Unsure of scope, explore first"

Mid-Workflow Commands

# Switch from polish to overhaul (during explore/brief)
refactor --switch-overhaul

# Resume after context compaction
rehydrate

Track Comparison

When to use refactor vs debug

Rule of thumb: if there is dissatisfaction with working code (hard to read, violates SOLID, duplicated logic), use refactor. If there is a symptom (something that should work but doesn't), use debug.

Characterization Testing (Both Tracks)

Before modifying any existing code behavior, capture current behavior as characterization tests. This is a mandatory pre-step for both tracks:

1. Before changes: Write tests that document what the code currently does (not what it should do). Exercise the code through the most appropriate observable seam (API, CLI, integration boundary, or function) with representative inputs and assert on actual outputs/effects.
2. During changes: Any characterization test failure means behavior changed. Evaluate: intentional or accidental?
3. After changes: Document which characterization test failures were expected. Remaining characterization tests become regression tests.

This aligns with Michael Feathers' approach in Working Effectively with Legacy Code — understand behavior before changing it.

Oracle-integrity gate (Both Tracks)

The characterization tests are your oracle — the safety net that tells you whether behavior changed. That net only holds if you do not edit the oracle mid-refactor. Before completing the refactor, inspect the test diff:

git diff -- tests/

The test oracle may be ADDED to during a refactor (new characterization tests, new cases), but an existing characterization assertion must never be silently modified. A silently-edited oracle invalidates the safety net: the test now passes against the changed behavior, hiding the very regression characterization was meant to catch. If a characterization assertion genuinely must change, that is a behavior change — call it out explicitly and justify it, do not fold it into the refactor diff unremarked.

Design-time Constraints (Both Tracks)

At the brief phase, before committing to an approach, surface a Constraints section anchored to the architectural invariants relevant to the refactor. This is the refactor design-time equivalent of /ideate's Phase 0 and uses the same single shared source of truth for the selection rules: see @skills/ideate/references/constraint-anchoring.md. Load .exarchos/invariants.md (cost-of-load: always-load entries) and emit the Constraints section. Catalog-registration gated: when no catalog is registered under .exarchos.yml: invariants.catalogs, surface no Constraints section and proceed directly. See @skills/refactor/references/brief-template.md for the brief-phase placement.

Polish Track

Fast path for small, contained refactors (<=5 files, single concern). Orchestrator may write code directly (exception to orchestrator constraints). No worktree, no delegation.

HSM phases: explore → brief → polish-implement → polish-validate → polish-update-docs → completed

For detailed phase instructions, state management, and auto-chain behavior, see @skills/refactor/references/polish-track.md.

Overhaul Track

Rigorous path for architectural changes, migrations, and multi-file restructuring. Uses full delegation model with worktree isolation.

HSM phases: explore → brief → overhaul-plan → overhaul-plan-review → overhaul-delegate → overhaul-review → overhaul-update-docs → synthesize → completed

For detailed phase instructions, skill invocations, and auto-chain behavior, see @skills/refactor/references/overhaul-track.md.

State Management

Initialize refactor workflow:

action: "init", featureId: "refactor-<slug>", workflowType: "refactor"

Use describe to discover the full state schema at runtime: exarchos_workflow({ action: "describe", actions: ["init"] }).

Phase Transitions and Guards

Sequential traversal required. Every phase MUST be traversed in order — you cannot skip phases, even if you have all the data for a later phase ready. For example, explore must transition to brief before overhaul-plan — attempting explore → overhaul-plan directly will be rejected by the HSM. From brief you must go to polish-implement or overhaul-plan, not directly to completed. Each transition requires its guard to be satisfied via updates sent alongside the phase parameter in a single set call. See @skills/refactor/references/polish-track.md or @skills/refactor/references/overhaul-track.md for the exact tool call at each step.

Every phase transition has a guard that must be satisfied. Before transitioning, consult @skills/checkpoint/references/phase-transitions.md for the exact prerequisite for each guard.

The pattern for every transition: send the guard prerequisite in updates and the target in phase in a single set call.

Schema Discovery

Use exarchos_workflow({ action: "describe", actions: ["update", "init"] }) for parameter schemas and exarchos_workflow({ action: "describe", playbook: "refactor" }) for phase transitions, guards, and playbook guidance.

Decision Runbooks

For track-selection criteria at the explore phase, query the decision runbook: exarchos_orchestrate({ action: "runbook", id: "scope-decision" })

This runbook provides structured criteria for choosing between polish and overhaul tracks based on file count, structural impact, and PR scope.

Track Switching

If scope expands beyond polish limits during explore or brief phase, use mcp__exarchos__exarchos_workflow with action: "update" to set track to "overhaul" and update explore.scopeAssessment.recommendedTrack.

Scope thresholds: If >5 files affected OR changes cross module boundaries -> recommend overhaul track.

Indicators to switch:

• More than 5 files affected
• Multiple concerns identified
• Cross-module changes needed
• Test coverage gaps require new tests

Output: "Scope expanded beyond polish limits. Switching to overhaul track."

Integration Points

CRITICAL: All skill invocations MUST use explicit Skill() tool calls:

Anti-Patterns

Exarchos Integration

When Exarchos MCP tools are available, emit events throughout the refactor workflow:

1. At workflow start (explore): mcp__exarchos__exarchos_event with action: "append" → workflow.started with workflowType "refactor"
2. On track selection: Auto-emitted by exarchos_workflow set when phase is provided — emits workflow.transition with selected track (polish/overhaul)
3. On each phase transition: Auto-emitted by exarchos_workflow set when phase is provided — emits workflow.transition with from/to/trigger/featureId
4. Overhaul track stacking: Handled by delegate (subagents use git commit + git push per implementer prompt)
5. Polish track commit: Single git commit -m "refactor: <description>" + git push — no multi-branch stacking needed
6. On complete: Auto-emitted by exarchos_workflow set when transitioning to terminal state — emits workflow.transition to "completed"