refactor
/refactor
Prowadzi refaktoryzację w trybach polish i overhaul, w fazach explore, brief, implement i validate, wyłącznie dla istniejącego kodu.
- Autor
- lvlup-sw ↗
- Repozytorium
- exarchos ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 24.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 15
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 24.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Prowadzi refaktoryzację w trybach polish i overhaul, w fazach explore, brief, implement i validate, wyłącznie dla istniejącego kodu.
Wyzwalacze z opisu
Oryginalny opis (EN)
Code improvement workflow with polish and overhaul tracks. Triggers: 'refactor', 'clean up', 'restructure', 'reorganize', or /refactor. Phases: explore, brief, implement, validate. Existing code only — Do NOT use for bug fixes (/debug) or new features (/ideate).
Jak działa
- Overview
- Triggers
- Workflow Overview
- Command Interface
- Track Comparison
- When to use refactor vs debug
- Characterization Testing (Both Tracks)
- Design-time Constraints (Both Tracks)
- Polish Track
- Overhaul Track
Podgląd SKILL.md
---
name: refactor
description: "Code improvement workflow with polish and overhaul tracks. Triggers: 'refactor', 'clean up', 'restructure', 'reorganize', or /refactor. Phases: explore, brief, implement, validate. Existing code only — Do NOT use for bug fixes (/debug) or new features (/ideate)."
metadata:
author: exarchos
version: 1.0.0
mcp-server: exarchos
category: workflow
phase-affinity:
- explore
- brief
- polish-implement
- polish-validate
- polish-update-docs
- overhaul-plan
- overhaul-plan-review
- overhaul-delegate
- overhaul-review
- overhaul-update-docs
- synthesize
---
# 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 `{{COMMAND_PREFIX}}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 `{{COMMAND_PREFIX}}refactor` when the code *works* but needs structural improvement. Use `{{COMMAND_PREFIX}}debug` when something is *broken* (error, crash, wrong behavior).
## Workflow Overview
```
{{COMMAND_PREFIX}}refactor
|
+-----+-----+
| Explore |
+-----+-----+
|
+--------------+--------------+
| |
--polish (default)
| |
v v
+--------------+ +--------------+
| Polish | | Overhaul |
| Track | | Track |
+--------------+ +--------------+
```
## Command Interface
### Start Refactor Workflow
```bash
# Default: overhaul track
{{COMMAND_PREFIX}}refactor "Description of what needs refactoring"
# Fast path: polish track
{{COMMAND_PREFIX}}refactor --polish "Small contained refactor description"
# Explore first, then decide track
{{COMMAND_PREFIX}}refactor --explore "Unsure of scope, explore first"
```
### Mid-Workflow Commands
```bash
# Switch from polish to overhaul (during explore/brief)
{{COMMAND_PREFIX}}refactor --switch-overhaul
# Resume after context compaction
{{COMMAND_PREFIX}}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) |
## When to use refactor vs debug
| Signal | Use {{COMMAND_PREFIX}}refactor | Use {{COMMAND_PREFIX}}debug |
|--------|--------------|-----------|
| Code works but is messy/complex | Yes | No |
| Something is broken or wrong | No | Yes |
| "This should be reorganized" | Yes | No |
| Users report a bug or regression | No | Yes |
| Performance degradation | Switch to {{COMMAND_PREFIX}}refactor if structural | Start with {{COMMAND_PREFIX}}debug (investigate) |
| SOLID violations in working code | Yes | No |
| Error in production logs | No | Yes |
**Rule of thumb:** if there is _dissatisfaction_ with working code (hard to read, violates SOLID, duplicated logic), use `{{COMMAND_PREFIX}}refactor`. If there is a _symptom_ (something that should work but doesn't), use `{{COMMAND_PREFIX}}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:
```bash
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_PREFIX}}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:
| Skill | Invocation | Usage |
|-------|------------|-------|
| `{{COMMAND_PREFIX}}plan` | `{{CHAIN next="plan" args="--refactor <state-file>"}}` | Task extraction from brief |
| `{{COMMAND_PREFIX}}delegate` | `{{CHAIN next="delegate" args="<state-file>"}}` | Subagent dispatch for TDD |
| `{{COMMAND_PREFIX}}review` | `{{CHAIN next="review" args="<state-file>"}}` | Quality review |
| `{{COMMAND_PREFIX}}synthesize` | `{{CHAIN next="synthesize" 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:
1. **At workflow start (explore):** `{{MCP_PREFIX}}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 `{{COMMAND_PREFIX}}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"
Pliki w paczce (15)
- SKILL.md 12 KB
- references/brief-template.md 4 KB
- references/doc-update-checklist.md 3 KB
- references/explore-checklist.md 2 KB
- references/overhaul-track.md 7 KB
- references/polish-track.md 5 KB
- references/phases/auto-chain.md 10 KB
- references/phases/brief.md 4 KB
- references/phases/explore.md 3 KB
- references/phases/overhaul-delegate.md 3 KB
- references/phases/overhaul-plan.md 9 KB
- references/phases/overhaul-review.md 8 KB
- references/phases/polish-implement.md 9 KB
- references/phases/polish-validate.md 5 KB
- references/phases/update-docs.md 6 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · lvlup-sw/exarchos | 100 | Apache-2.0 |
| froglet-studio/cosmic-shore | 100 | MIT |
| mgiovani/cc-arsenal | 100 | MIT |
| jongio/skills | 100 | MIT |
| boshu2/agentops | 100 | Apache-2.0 |
| y-miyazaki/terraform-aws-base | 100 | Apache-2.0 |
| mickeyyaya/evolve-loop | 100 | Apache-2.0 |
| j0hanz/j0hanz-marketplace | 100 | MIT |
| kriscard/kriscard-claude-plugins | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 5e8f346f8c7f (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100refactor-team
Prowadzi zespołową refaktoryzację kodu z analizą i zmianami zatwierdzanymi przez użytkownika. - 90implement
Prowadzi pisanie kodu, budowanie funkcji, naprawę błędów, refaktoryzację i wieloetapową pracę implementacyjną. - 100tdd
Prowadzi przenośny przepływ czerwony, zielony, refaktoryzacja dla funkcji, poprawek i zmian semantyki istniejącego kodu. - 100codebase-cleanup-refactor-clean
Refaktoryzuje kod według zasad czystego kodu i SOLID, poprawiając jakość, utrzymywalność i wydajność istniejącego projektu. - 100refactor-plan
Analizuje kod pod kątem duplikacji i złożoności oraz przygotowuje plan działań refaktoryzacyjnych na poziomie kodu. - 100workflow-refactor
Wykonuje refaktoryzację o ograniczonym zakresie, zachowującą działanie kodu: mapuje zależności, zmienia strukturę i uruchamia testy dotkniętych miejsc.