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

bash

# 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

bash

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

# Resume after context compaction
/rehydrate

Track Comparison

Aspect	Polish	Overhaul
Scope	<=5 files, single concern	No limit
Worktree	No (direct)	Yes (isolated)
Delegation	No	Yes (full workflow)
Documentation	Mandatory update phase	Mandatory update phase
Human Checkpoints	0	1 (merge)

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:

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.
During changes: Any characterization test failure means behavior changed. Evaluate: intentional or accidental?
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.

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/workflow-state/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: ["set", "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: "set"

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:

Skill	Invocation	Usage
`/plan`	`[Invoke the exarchos:plan skill with args: --refactor <state-file>]`	Task extraction from brief
`/delegate`	`[Invoke the exarchos:delegate skill with args: <state-file>]`	Subagent dispatch for TDD
`/review`	`[Invoke the exarchos:review skill with args: <state-file>]`	Quality review
`/synthesize`	`[Invoke the exarchos:synthesize skill with args: <feature>]`	PR creation

Anti-Patterns

Don't	Do Instead
Skip exploration	Always assess scope first (see `references/explore-checklist.md` )
Use polish for large changes	Switch to overhaul when scope expands
Skip doc updates	Documentation is mandatory (see `references/doc-update-checklist.md` )
Add features during refactor	Scope creep - stick to brief goals
Skip tests because "just moving code"	Refactors need test verification
Create design document for polish	Use brief in state file instead
Work in main for overhaul	Use worktree isolation

Exarchos Integration

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

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

refactor

NPX Install

Tags

SKILL.md Content