/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

Section	Purpose
Auto Mode Detection	Detect bypass/yolo mode for autonomous execution
Git Isolation	Worktree-based isolation for all refactoring work
Workflow Summary	5-phase pipeline overview
Quick Modes	Scoped invocations for targeted refactoring
Cross-Reference Map	Skill routing by issue type
Reference	Detailed phase docs, catalogs, techniques

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

File	When to read
reference/workflow.md	Detailed Phases 1-5 with subagent prompts and merge protocol
reference/scan-pipeline.md	Phase 1: parallel tool execution + speed optimizations
reference/continuous-integration.md	PR review integration, debt tracking, velocity dashboards

Detection & Scoring

File	When to read
reference/code-smells.md	Phase 1: detecting code smells (22 smells, thresholds)
reference/complexity-scoring.md	Phase 1: computing cognitive complexity scores
reference/architecture-analysis.md	Phase 1: circular deps, boundaries, fan-in/fan-out
reference/health-scoring.md	Phase 2: computing composite priority scores

Techniques & Mapping

File	When to read
reference/refactoring-techniques.md	Phase 3: selecting technique for each detected smell (66 techniques)
reference/smell-to-technique-map.md	Quick lookup: smell → fix technique + skill

Safety & Execution

File	When to read
reference/safety-protocols.md	Phase 4: LLM safety, RefactoringMirror, re-prompting
reference/prompt-engineering.md	Phase 4: crafting subagent prompts (specificity ladder)

Language & Examples

File	When to read
reference/language-notes.md	Phase 3-4: TS/JS, Python, Go, Java specifics
reference/worked-example.md	First time: full pipeline walkthrough (UserService)