| name | refactor |
| description | Use when the user asks to refactor code, review code quality, or fix code smells — orchestrates the full refactoring pipeline from detection through fix, with parallel worktree isolation per independent refactoring group |
| argument-hint | [scan|fix|security|performance|review|auto|arch|complexity|health|diff|hotspots] |
/evo:refactor — Full Refactoring Pipeline
Orchestrate the complete refactoring workflow: detect smells, prioritize by weighted scoring, partition into independent groups, execute in parallel worktrees via subagents, merge and verify. Enhanced with cognitive complexity scoring, architecture analysis, and speed-optimized parallel scan pipelines.
Contents
Auto Mode Detection
Before starting, check if the user is in bypass/yolo mode (auto-accept permissions enabled). Detection signals:
- User explicitly said "yolo mode", "bypass permissions", or "auto-accept"
- The session is running with
--dangerously-skip-permissions or equivalent
- Tools are being auto-approved without user prompts
When auto mode is detected: Skip all confirmation prompts. Automatically select all issues, partition, launch parallel subagents, and merge passing branches without pausing. This enables fully autonomous refactoring.
When auto mode is NOT detected: Pause for user confirmation at each checkpoint described in reference/workflow.md.
Git Isolation (MANDATORY)
All refactoring work MUST be done in isolated git worktrees branched from main. Never commit directly to main.
Execution Modes
The orchestrator selects the execution mode based on the partition result from Phase 3:
| Condition | Mode | Worktrees |
|---|
| 1 group or all issues touch the same files | Sequential | 1 worktree, 1 branch |
| N independent groups with no file overlap | Parallel | N worktrees, N branches, N subagents |
Worktree Naming Convention
../refactor-wt-<group-slug> → branch: refactor/<group-slug>
Examples:
../refactor-wt-extract-auth → refactor/extract-auth
../refactor-wt-simplify-payment → refactor/simplify-payment
../refactor-wt-cleanup-utils → refactor/cleanup-utils
Workflow Summary
Phase 1 SCAN ──────────── on main (read-only, parallel tool pipeline)
Phase 2 PRIORITIZE ────── on main (read-only, weighted scoring)
Phase 3 PLAN & PARTITION ─ on main (read-only, graph-based critical pair analysis)
Phase 4 EXECUTE ────────── in worktrees (parallel subagents, up to 3 passes)
Phase 5 MERGE & VERIFY ── back on main (sequential merge, final scan)
For the full phase-by-phase protocol including subagent prompts, isolation rules, and merge handling, read reference/workflow.md.
For scan tool launch and speed optimizations, read reference/scan-pipeline.md.
Quick Modes
The user can scope the refactoring with arguments:
| Command | Behavior |
|---|
/evo:refactor | Full pipeline on current file or user-specified files |
/evo:refactor scan | Phase 1 only — detect and report, no changes |
/evo:refactor fix <smell> | Skip to Phase 3-4 for a specific known smell |
/evo:refactor security | Security-focused scan using security-patterns-code-review |
/evo:refactor performance | Performance-focused scan using performance-anti-patterns |
/evo:refactor review | Full code review using review-cheat-sheet as guide |
/evo:refactor auto | Force auto mode — plan, partition, execute in parallel, merge without confirmation |
/evo:refactor arch | Architecture-only analysis — circular deps, boundaries, centrality |
/evo:refactor complexity | Cognitive complexity report only — no fixes |
/evo:refactor health | Composite health score per function — multi-metric scoring |
/evo:refactor diff | Scan only files changed since last commit |
/evo:refactor hotspots | Git-history analysis — find high-churn, high-smell files |
Cross-Reference Map
| When you find... | Use skill... |
|---|
| Code smells | detect-code-smells |
| Anti-patterns | anti-patterns-catalog |
| Which technique to use | refactoring-decision-matrix |
| Long/complex methods | refactor-composing-methods |
| Misplaced responsibilities | refactor-moving-features |
| Data handling issues | refactor-organizing-data |
| Complex conditionals | refactor-simplifying-conditionals |
| Bad method interfaces | refactor-simplifying-method-calls |
| Inheritance problems | refactor-generalization |
| FP improvements | refactor-functional-patterns |
| Type safety gaps | type-system-patterns |
| Design pattern opportunity | design-patterns-creational-structural, design-patterns-behavioral |
| Architecture violations | architectural-patterns |
| Security vulnerabilities | security-patterns-code-review |
| Performance issues | performance-anti-patterns |
| Database problems | database-review-patterns |
| Error handling gaps | error-handling-patterns |
| Concurrency bugs | concurrency-patterns |
| Test quality issues | testing-patterns |
| Observability gaps | observability-patterns |
| DI/coupling problems | dependency-injection-module-patterns |
| Language anti-idioms | language-specific-idioms |
| API contract issues | review-api-contract |
| SOLID violations | review-solid-clean-code |
| Full code review | review-cheat-sheet |
Reference (read on demand)
Pipeline Execution
Detection & Scoring
Techniques & Mapping
Safety & Execution
Language & Examples
