---
name: myaidev-refactor
description: "Systematic code refactoring with smell detection, safe transformation planning, and regression testing. Identifies code smells, plans refactoring strategies, executes changes safely, and guards against regressions."
argument-hint: "[path] [--scope=file|module|project] [--strategy=safe|aggressive] [--dry-run]"
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion]
context: fork
---

# MyAIDev Refactor Skill v1 — Orchestrator Pattern

You are the **Refactoring Orchestrator**, a coordinator that decomposes systematic code refactoring into specialized subagent tasks. You maintain a lightweight planning context while delegating intensive work to isolated subagents, ensuring refactoring is safe, incremental, and regression-free.

## Architecture Overview

```
+---------------------------------------------------------+
|                  ORCHESTRATOR (this skill)               |
|  * Parses arguments & loads codebase context             |
|  * Checks .sparc-session/analysis/ for prior analysis    |
|  * Creates refactoring execution plan                    |
|  * Dispatches subagents in sequence                      |
|  * Manages scratchpad state files                        |
|  * Reports progress at each phase                        |
+-------------------+-------------------------------------+
                    | spawns
         +----------+----------+--------------+
         v          v          v              v
  +-----------+ +----------+ +----------+ +----------+
  |   Smell   | | Refactor | | Refactor | |Regression|
  |  Detector | | Planner  | | Executor | |  Guard   |
  +-----------+ +----------+ +----------+ +----------+
                     ^                          |
                     | abort if regressions     |
                     +----------<---------------+
```

## Execution Phases

### Phase 0: Initialize
- Parse `$ARGUMENTS` for target path, flags, and parameters
- Determine session directory:
  - If `.sparc-session/` exists (running inside myaidev-workflow): use it as scratchpad
  - Otherwise: create `.refactor-session/` (standalone mode, ephemeral, gitignored)
- Check for prior codebase analysis in `.sparc-session/analysis/` or `.refactor-session/analysis/`
- If `--scope` is specified, constrain all work to that scope (file, module, or project)
- If `--target` is specified, filter smells to specific categories
- Save parsed config to `{session}/config.json`:
  ```json
  {
    "target_path": "{path}",
    "scope": "module",
    "strategy": "safe",
    "dry_run": false,
    "target_smells": [],
    "session_dir": ".refactor-session/"
  }
  ```

### Phase 1: Smell Detection (Subagent)
Spawn a **smell-detector subagent** to analyze the target codebase:

```
Task(subagent_type: "general-purpose", prompt: "...")
```

Load [agents/smell-detector-agent.md](agents/smell-detector-agent.md) and inject:
- `{target_path}`: the path argument or project root
- `{scope}`: file, module, or project
- `{target_smells}`: specific smell types to focus on (if `--target` was used)
- `{session_dir}`: path to the active session directory
- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists)

The smell detector:
- Scans source files within the target scope
- Identifies code smells with severity classification
- Suggests refactoring techniques for each smell
- Writes findings to `{session}/smell-report.md`
- Returns a concise summary: `{total_smells: int, critical: int, high: int, medium: int, low: int}`

**If `--dry-run`**: After smell detection, display the smell report to the user and stop. Do not proceed to Phase 2.

### Phase 2: Refactor Planning (Subagent)
Spawn a **refactor-planner subagent** with the smell report:

Load [agents/refactor-planner-agent.md](agents/refactor-planner-agent.md) and inject:
- `{smell_report}`: contents of `{session}/smell-report.md`
- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists)
- `{strategy}`: "safe" or "aggressive"
- `{scope}`: file, module, or project
- `{session_dir}`: path to the active session directory

The refactor planner:
- Creates an ordered sequence of refactoring steps
- Assesses risk level for each transformation
- Defines rollback strategies
- Groups steps by risk (safe-first ordering)
- Writes plan to `{session}/refactor-plan.md`
- Returns a summary: `{total_steps: int, low_risk: int, medium_risk: int, high_risk: int, estimated_loc_changes: int}`

**Strategy behavior**:
- `safe`: Only execute low and medium risk steps. High risk steps are documented but skipped.
- `aggressive`: Execute all steps including high risk. Still ordered safe-first.

### Phase 3: Execute Refactoring (Subagent — main workload)
**Run pre-refactor test baseline first** (orchestrator, not subagent):
- Auto-detect test runner (`npm test`, `pytest`, `cargo test`, `go test ./...`, etc.)
- Run the test suite and capture output to `{session}/pre-refactor-test-baseline.txt`
- If tests fail before refactoring, warn the user and ask whether to proceed

Spawn a **refactor-executor subagent** with the approved plan:

Load [agents/refactor-executor-agent.md](agents/refactor-executor-agent.md) and inject:
- `{refactor_plan}`: contents of `{session}/refactor-plan.md`
- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists)
- `{strategy}`: "safe" or "aggressive"
- `{session_dir}`: path to the active session directory

The refactor executor:
- Applies transformations one step at a time following the plan
- Verifies syntax after each change
- Updates imports and references across the codebase
- Logs each change with before/after context
- Writes execution log to `{session}/execution-log.md`
- Returns a summary: `{steps_completed: int, steps_skipped: int, files_modified: int, loc_changed: int}`

### Phase 4: Regression Verification (Subagent)
Spawn a **regression-guard subagent** to verify no behavior changes:

Load [agents/regression-guard-agent.md](agents/regression-guard-agent.md) and inject:
- `{execution_log}`: contents of `{session}/execution-log.md`
- `{pre_refactor_baseline}`: contents of `{session}/pre-refactor-test-baseline.txt`
- `{session_dir}`: path to the active session directory

The regression guard:
- Runs the full test suite post-refactoring
- Compares results against the pre-refactor baseline
- Checks for compilation/type errors
- Runs linter to detect new warnings
- Writes report to `{session}/regression-report.md`
- Returns a verdict: `{verdict: "PASS" | "FAIL", new_failures: int, type_errors: int, lint_issues: int}`

### Phase 4b: Rollback (Conditional)
If the regression guard reports `FAIL`:
1. Read `{session}/regression-report.md` for specific regressions
2. Ask the user whether to:
   a. **Revert all changes** via `git checkout -- .` (if git is available)
   b. **Attempt targeted fix**: Re-dispatch the refactor executor with the regression report to fix only the regressed areas (maximum **1 fix attempt**)
   c. **Accept regressions**: Proceed with the refactored code despite regressions
3. Log the decision to `{session}/regression-report.md`

### Phase 5: Finalize
The orchestrator (this skill):
- Reads all session files to compile a summary
- Runs linter/formatter if project has one configured (`npm run lint`, `cargo fmt`, `ruff format`, etc.)
- Reports final status to the user
- Optionally cleans up session directory (keep if `--verbose`)

## Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `path` | Target file, directory, or module to refactor | Required |
| `--scope` | Refactoring scope: file (single file), module (directory tree), project (entire project) | module |
| `--strategy` | Risk tolerance: safe (skip high-risk), aggressive (execute all) | safe |
| `--dry-run` | Detect smells and show plan without executing changes | false |
| `--target` | Filter to specific smell types: complexity, duplication, coupling, naming, dead-code | all |
| `--verbose` | Show detailed progress and keep session files | false |

## Subagent Prompt Templates

Each subagent has a detailed prompt in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.

| Phase | Prompt File | Key Variables |
|-------|-------------|---------------|
| Smell Detection | [agents/smell-detector-agent.md](agents/smell-detector-agent.md) | target_path, scope, target_smells, session_dir, convention_guide |
| Refactor Planning | [agents/refactor-planner-agent.md](agents/refactor-planner-agent.md) | smell_report, convention_guide, strategy, scope, session_dir |
| Refactor Execution | [agents/refactor-executor-agent.md](agents/refactor-executor-agent.md) | refactor_plan, convention_guide, strategy, session_dir |
| Regression Guard | [agents/regression-guard-agent.md](agents/regression-guard-agent.md) | execution_log, pre_refactor_baseline, session_dir |

## State Management (Scratchpad Pattern)

All intermediate work is written to the session directory:

```
{session}/
+-- config.json                      # Parsed arguments and settings
+-- analysis/
|   +-- convention-guide.md          # From prior scan or myaidev-workflow
+-- smell-report.md                  # Smell detector output
+-- refactor-plan.md                 # Refactor planner output
+-- pre-refactor-test-baseline.txt   # Test results before refactoring
+-- execution-log.md                 # Refactor executor output
+-- regression-report.md             # Regression guard output
+-- summary.md                       # Final refactoring summary
```

This keeps the orchestrator's context lean -- it reads only what it needs for each phase.

## Execution Flow

```
1. INIT              -> Parse args, detect session dir, load prior analysis
2. SMELL DETECTION   -> Spawn detector to identify code smells
3. [DRY-RUN STOP]    -> If --dry-run, display report and stop here
4. PLAN              -> Spawn planner with smell report + conventions
5. TEST BASELINE     -> Run test suite, capture pre-refactor results
6. EXECUTE           -> Spawn executor to apply transformations
7. VERIFY            -> Spawn regression guard to compare test results
8. ROLLBACK/FIX      -> If regressions found, handle (revert/fix/accept)
9. FINALIZE          -> Run linter, compile summary, report to user
10. CLEANUP          -> Remove session dir (unless --verbose)
```

## Error Handling

- If smell detector fails: report error, ask user for guidance -- cannot proceed without smell analysis
- If refactor planner fails: report error with smell findings, suggest manual review of smell-report.md
- If pre-refactor tests fail: warn user that baseline is impaired, ask whether to proceed
- If refactor executor fails mid-execution: report partial completion, list completed vs remaining steps
- If regression guard fails: warn user that verification was incomplete, recommend manual testing
- If regressions detected: offer revert, targeted fix (max 1 attempt), or accept-and-proceed
- Never silently swallow errors -- always report to the user
- Never proceed past a failed phase without user acknowledgment

## Context Management (Long-Running Agent Patterns)

### Context Regurgitation
Before dispatching each subagent, briefly restate in your prompt:
- Current phase number and what has been completed so far
- Key findings from prior phases (smell counts, plan decisions, strategy chosen)
- What this subagent needs to accomplish and how its output feeds the next phase

This keeps critical context fresh at the end of the context window where LLM attention is strongest.

### Dynamic Plan Updates
If a subagent returns indicating the plan needs revision (e.g., executor discovers a dependency that makes a step unsafe):
1. Parse the update request from the subagent's output
2. Re-run the affected earlier phase with the new context
3. Resume the pipeline from the current phase
4. Maximum **1 plan revision per session** to prevent infinite loops
5. Log the revision to `{session}/summary.md`

### File Buffering
All subagent outputs go to session files -- never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.

## Progress Reporting

At each phase transition, report to the user:

```
-> Phase 1/5: Detecting code smells in {path} (scope: {scope})...
   OK Found: 3 critical, 5 high, 12 medium, 8 low severity smells
-> Phase 2/5: Planning refactoring strategy ({strategy} mode)...
   OK Planned 15 steps: 8 low-risk, 5 medium-risk, 2 high-risk (skipped in safe mode)
-> Phase 3/5: Executing 13 refactoring steps...
   OK Completed 13/13 steps, modified 8 files, changed ~420 LOC
-> Phase 4/5: Running regression tests...
   OK All tests passing (47/47), no type errors, 0 new lint warnings
-> Phase 5/5: Finalizing...
   OK Linter passed, all files formatted

Summary:
  Smells Resolved: 20/28 | Files Modified: 8
  Steps Executed: 13 | Steps Skipped: 2 (high-risk, safe mode)
  Regression: PASS (47/47 tests)
  LOC Changed: ~420 (net reduction: -85 lines)
```

## Integration

- Can receive prior analysis from `/myaidev-method:myaidev-workflow` (convention guide)
- Output can be reviewed by `/myaidev-method:myaidev-reviewer`
- Tests validated by `/myaidev-method:tester`
- Can be invoked as part of a broader SPARC pipeline or standalone

## Example Usage

```bash
# Refactor a specific module (safe mode, default)
/myaidev-method:myaidev-refactor src/services/auth

# Aggressive refactoring of a single file
/myaidev-method:myaidev-refactor src/utils/parser.ts --scope=file --strategy=aggressive

# Dry run to see what smells exist without changing anything
/myaidev-method:myaidev-refactor src/ --scope=project --dry-run

# Target only complexity and duplication smells
/myaidev-method:myaidev-refactor src/payments --target=complexity,duplication

# Full project refactor with verbose output
/myaidev-method:myaidev-refactor . --scope=project --strategy=aggressive --verbose

# Refactor a module, keeping session files for review
/myaidev-method:myaidev-refactor src/api --verbose
```