---
name: refactor
description: |
  Structured 9-phase refactoring workflow with three execution modes:
  Full (all phases), Targeted (skip discovery), Quick Assessment (phases 0-2 only).
  Supports project mode (_docs/) and standalone mode (@file.md).
category: evolve
tags: [refactoring, coupling, technical-debt, performance, hardening]
trigger_phrases: ["refactor", "refactoring", "improve code", "analyze coupling", "decoupling", "technical debt", "code quality"]
disable-model-invocation: true
---

# Structured Refactoring

Phase details live in `phases/` — read the relevant file before executing each phase.

## Core Principles

- **Preserve behavior first**: never refactor without a passing test suite
- **Measure before and after**: every change must be justified by metrics
- **Small incremental changes**: commit frequently, never break tests
- **Save immediately**: write artifacts to disk after each phase
- **Ask, don't assume**: when scope or priorities are unclear, STOP and ask the user

## Context Resolution

Determine operating mode before any other logic runs. Announce detected mode and paths to user.

| | Project mode (default) | Standalone mode (`/refactor @file.md`) |
|---|---|---|
| PROBLEM_DIR | `_docs/00_problem/` | N/A |
| SOLUTION_DIR | `_docs/01_solution/` | N/A |
| COMPONENTS_DIR | `_docs/02_document/components/` | N/A |
| DOCUMENT_DIR | `_docs/02_document/` | N/A |
| REFACTOR_DIR | `_docs/04_refactoring/` | `_standalone/refactoring/` |
| Prereqs | `problem.md` required, `acceptance_criteria.md` warn if absent | INPUT_FILE must exist and be non-empty |

Create REFACTOR_DIR if missing. If it already has artifacts, ask user: **resume or start fresh?**

## Workflow

| Phase | File | Summary | Gate |
|-------|------|---------|------|
| 0 | `phases/00-baseline.md` | Collect goals, capture baseline metrics | BLOCKING: user confirms |
| 1 | `phases/01-discovery.md` | Document components, synthesize solution | BLOCKING: user confirms |
| 2 | `phases/02-analysis.md` | Research improvements, produce roadmap | BLOCKING: user confirms |
| | | *Quick Assessment stops here* | |
| 3 | `phases/03-safety-net.md` | Design and implement pre-refactoring tests | GATE: all tests pass |
| 4 | `phases/04-execution.md` | Analyze coupling, execute decoupling | BLOCKING: user confirms |
| 5 | `phases/05-hardening.md` | Technical debt, performance, security | Optional: user picks tracks |
| 6 | `phases/06-test-sync.md` | Remove obsolete, update broken, add new tests | GATE: all tests pass |
| 7 | `phases/07-verification.md` | Run full suite, compare metrics vs baseline | GATE: all pass, no regressions |
| 8 | `phases/08-documentation.md` | Update `_docs/` to reflect refactored state | Skip in standalone mode |

**Mode detection:**
- "quick assessment" / "just assess" → phases 0–2
- "refactor [specific target]" → skip phase 1 if docs exist
- Default → all phases

At the start of execution, create a TodoWrite with all applicable phases.

## Artifact Structure

All artifacts are written to REFACTOR_DIR:

```
baseline_metrics.md                      Phase 0
discovery/components/[##]_[name].md      Phase 1
discovery/solution.md                    Phase 1
discovery/system_flows.md                Phase 1
analysis/research_findings.md            Phase 2
analysis/refactoring_roadmap.md          Phase 2
test_specs/[##]_[test_name].md           Phase 3
coupling_analysis.md                     Phase 4
execution_log.md                         Phase 4
hardening/{technical_debt,performance,security}.md   Phase 5
test_sync/{obsolete_tests,updated_tests,new_tests}.md  Phase 6
verification_report.md                   Phase 7
doc_update_log.md                        Phase 8
FINAL_report.md                          after all phases
```

**Resumability**: match existing artifacts to phases above, resume from next incomplete phase.

## Final Report

After all phases complete, write `REFACTOR_DIR/FINAL_report.md`:
mode used, phases executed, baseline vs final metrics, changes summary, remaining items, lessons learned.

## Escalation Rules

| Situation | Action |
|-----------|--------|
| Unclear scope or ambiguous criteria | **ASK user** |
| Tests failing before refactoring | **ASK user** — fix tests or fix code? |
| Risk of breaking external contracts | **ASK user** |
| Performance vs readability trade-off | **ASK user** |
| No test suite or CI exists | **WARN user**, suggest safety net first |
| Security vulnerability found | **WARN user** immediately |