Refactor
Restructure code without changing external behavior using TDD discipline.
Quick Start
/refactor src/services/auth.py
/refactor src/utils/ --scope module
/refactor "split UserService into smaller services" --scope cross-module
/refactor src/core/ --scope architecture --pattern mikado
MANDATORY EXECUTION RULES (READ FIRST):
- 🔴 NEVER modify behavior (must preserve external API)
- 🔴 NEVER skip tests (TDD Red-Green-Refactor enforced)
- 🔴 NEVER continue if tests fail (revert immediately)
- 🔴 NEVER skip the BREAKPOINT at plan validation (step-03)
- 🔴 NEVER call EnterPlanMode during skill execution
- ✅ ALWAYS start with step-00-init.md
- ✅ ALWAYS follow next_step from each step
- ✅ ALWAYS detect stack skills at initialization
- ✅ ALWAYS generate metrics before AND after
- ⛔ FORBIDDEN applying untested changes
- 🔵 YOU ARE A DISCIPLINED REFACTORER following TDD
EXECUTION PROTOCOLS:
- Load step-00-init.md
- Execute current step protocols completely
- Present breakpoint at step-03 (plan validation)
- Evaluate next step trigger conditions
- Proceed to next_step or conditional_next
CONTEXT BOUNDARIES:
- IN scope: Code restructuring, architecture improvement, technical debt reduction
- OUT scope: Feature changes (use /implement), bug fixes (use /debug), performance optimization (use /improve)
Workflow Overview
┌─────────────────────────────────────────────────────────────────┐
│ REFACTOR WORKFLOW (TDD) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 00: INIT │
│ ├─ Parse input (target, scope, pattern) │
│ ├─ Auto-detect stack skills │
│ └─ Launch @Explore in background │
│ │
│ Step 01: ANALYSIS │
│ ├─ Metrics BEFORE (CC, LOC, dependencies) │
│ ├─ Detect code smells (Claude + rules) │
│ └─ Build dependency graph │
│ │
│ Step 02: PLANNING │
│ ├─ Select refactoring patterns │
│ ├─ Define step-by-step transformations │
│ └─ IF Architecture scope → Mikado Method graph │
│ │
│ Step 03: BREAKPOINT │
│ └─ User validates refactoring plan │
│ └─ Options: [A] Execute [B] Modify [C] Cancel │
│ │
│ Step 04: EXECUTE │
│ ├─ TDD: RED → GREEN → REFACTOR (per transformation) │
│ ├─ Atomic commits (if requested) │
│ └─ Revert on test failure │
│ │
│ Step 05: REVIEW (conditional) │
│ ├─ @code-reviewer (if Module+ scope) │
│ ├─ @security-auditor (if auth/security patterns) │
│ └─ @qa-reviewer (if 5+ test files modified) │
│ │
│ Step 06: VERIFY │
│ ├─ Run full test suite │
│ ├─ Metrics AFTER │
│ └─ Compare delta │
│ │
│ Step 07: REPORT │
│ ├─ Generate metrics report (delta per file) │
│ ├─ Update project-memory │
│ └─ Suggest /commit if changes ready │
│ │
└─────────────────────────────────────────────────────────────────┘
Scopes
| Scope |
Target |
Files |
Reviews |
Example |
single |
One file |
1 |
Skip |
Extract method from large function |
module |
Directory/module |
2-5 |
Conditional |
Split service into smaller files |
cross-module |
Multiple modules |
5-15 |
Always |
Extract shared utilities |
architecture |
System-wide |
15+ |
Always |
Apply Strangler Fig pattern |
Auto-detection: If no --scope provided, inferred from target path and complexity.
Patterns
| Pattern |
Description |
Scope |
extract-method |
Pull code into new method |
single |
extract-class |
Create new class from code |
single, module |
extract-module |
Create new module/file |
module |
inline |
Merge small units back |
single |
encapsulate |
Hide implementation details |
single, module |
rename |
Consistent naming across codebase |
all |
move |
Relocate code to better location |
module+ |
strangler-fig |
Gradual replacement of legacy |
architecture |
branch-by-abstraction |
Abstract before replace |
architecture |
mikado |
Dependency-aware transformation |
architecture |
See references/refactoring-patterns.md for details.
Flags
| Flag |
Default |
Description |
--scope <scope> |
auto |
Force scope: single, module, cross-module, architecture |
--pattern <pattern> |
auto |
Suggest pattern: extract, inline, rename, strangler-fig, mikado |
--turbo |
off |
Use @implementer, skip reviews, minimal breakpoints |
--dry-run |
off |
Generate plan only, no execution |
--atomic |
off |
Create atomic commits per transformation |
--no-metrics |
off |
Skip metrics collection |
Steps
| Step |
Name |
Description |
Skippable |
| 00 |
init |
Parse input, detect stack, launch @Explore |
No |
| 01 |
analysis |
Metrics before, code smells, dependency graph |
No |
| 02 |
planning |
Pattern selection, transformation plan |
No |
| 03 |
breakpoint |
User validation of plan |
No |
| 04 |
execute |
TDD cycle per transformation |
No |
| 05 |
review |
Conditional code/security/qa reviews |
Conditional |
| 06 |
verify |
Tests, metrics after, delta |
No |
| 07 |
report |
Final report, memory update |
No |
Step Files
Reference Files
Templates
Shared Components Used
epci:complexity-calculator — Scope estimationepci:tdd-enforcer — TDD Red-Green-Refactor cycleepci:breakpoint-system — Plan validation (step-03)epci:state-manager — Track multi-session refactorsepci:project-memory — Store refactoring patterns
Subagents
| Agent |
Model |
Trigger |
@Explore |
- |
Always at init (background) |
@implementer |
Sonnet |
--turbo mode or Single scope |
@code-reviewer |
Opus |
Module+ scope, >5 files |
@security-auditor |
Opus |
Files match **/auth/**, **/security/** |
@qa-reviewer |
Sonnet |
>= 5 test files modified |
Subagent Invocation Matrix
| Subagent |
Single |
Module |
Cross-Module |
Architecture |
| @Explore |
Yes |
Yes |
Yes |
Yes |
| @implementer |
turbo |
turbo |
turbo |
Skip |
| @code-reviewer |
Skip |
>5 files |
Always |
Always |
| @security-auditor |
patterns |
patterns |
patterns |
Always |
| @qa-reviewer |
Skip |
>5 tests |
Always |
Always |
Stack Skills (Auto-detected)
| Stack |
Trigger Files |
Refactoring Context |
python-django |
manage.py, django in deps |
Service layer patterns, pytest |
javascript-react |
react in package.json |
Component patterns, Jest |
java-springboot |
spring-boot in pom/gradle |
Bean patterns, JUnit |
php-symfony |
symfony in composer.json |
Service patterns, PHPUnit |
frontend-editor |
tailwind.config.* |
Component extraction |
Metrics Tools (Adaptive)
| Stack |
Tool |
Fallback |
| Python |
radon, xenon, lizard |
Claude estimation |
| PHP |
phploc |
Claude estimation |
| JavaScript |
lizard, eslint-complexity |
Claude estimation |
| Java |
lizard, checkstyle |
Claude estimation |
Error Handling
| Error |
Cause |
Resolution |
| Tests fail |
Behavior changed |
Revert, adjust transformation |
| No tests exist |
Missing coverage |
Warn user, proceed cautiously |
| Circular dependency |
Architecture issue |
Use Mikado Method |
| Metrics tool missing |
Not installed |
Use Claude estimation |
| Scope too large |
Underestimated |
Split into phases |
INVOCATION PROTOCOL (CRITICAL)
Les syntaxes @skill:epci:xxx et @agent:xxx dans les step files sont DOCUMENTAIRES SEULEMENT.
Claude interprète les blocs de code comme des exemples, pas comme des instructions d'exécution.
Pour invoquer réellement:
| Type |
Syntaxe documentaire |
Invocation réelle |
| Breakpoints |
@skill:epci:breakpoint-system |
Section impérative + AskUserQuestion explicite |
| Agents |
@agent:code-reviewer |
Task({ subagent_type: "code-reviewer", ... }) |
| Agents |
@agent:security-auditor |
Task({ subagent_type: "security-auditor", ... }) |
| Agents |
@agent:Explore |
Task({ subagent_type: "Explore", ... }) |
| Stack skills |
@skill:python-django |
Read("src/skills/stack/python-django/SKILL.md") |
Règle pour auteurs de step files:
- Utiliser le format impératif direct (pas dans bloc de code)
- Afficher les boîtes ASCII hors bloc exécutable
- Appeler AskUserQuestion explicitement
- Ajouter
⏸️ ATTENDS la réponse après chaque breakpoint
Limitations
This skill does NOT:
- Add new features (use /implement)
- Fix bugs (use /debug)
- Optimize performance (use /improve)
- Generate tests from scratch (expects existing tests)
- Modify external API contracts
- Handle database migrations