/refactor

name: refactor
description: Autonomous iterative refactoring workflow. Scans for tactical code quality improvements (DRY, dead code, naming, complexity), implements through SMEs, verifies with QA, commits atomically, and loops until no improvements remain.
model: opus

Refactor - Iterative Code Quality Improvement

Autonomous refactoring workflow that iteratively improves code quality within the existing architecture, always preferring the least aggressive change available, until no further opportunities exist.

Philosophy

**Clarity is the goal.** Every iteration should make the codebase easier to form a correct mental model of. Red diffs are the strongest signal - less code almost always means clearer code, and every iteration should delete more than it adds. But when reducing lines would hurt comprehensibility, clarity wins.

**Err on the side of trying.** When uncertain whether a refactoring is worthwhile, attempt it anyway. Git makes failed experiments free - the workflow will revert changes that don't pass QA. Missed opportunities are invisible; failed attempts teach you something. Be bold, knowing that version control provides the safety net.

**Work within the existing architecture.** This workflow improves code quality - DRY, dead code, naming, complexity - without questioning module boundaries or reorganizing the system. For architectural analysis (noun extraction, module dissolution, blueprint-driven restructuring), use `/review-arch` instead.

Workflow Overview

┌─────────────────────────────────────────────────────┐
│                  REFACTORING LOOP                   │
├─────────────────────────────────────────────────────┤
│  1. Determine scope                                 │
│  2. Select aggression ceiling                       │
│  3. Gather QA instructions                          │
│  4. Spawn fresh swe-code-reviewer agent (full scan)      │
│  5. Select least aggressive changes available       │
│  6. If none remain → exit to summary                │
│  7. Spawn SME agent (implement batch)               │
│  8. Spawn QA agent (verify)                         │
│     ├─ PASS → commit, goto 4                        │
│     └─ FAIL → retry (max 3), then abort batch       │
│  9. Completion summary                              │
│ 10. Update documentation (/tidy-docs)              │
└─────────────────────────────────────────────────────┘

Workflow Details

1. Determine Scope

**Default:** Entire codebase.

**Boundary: version-controlled files only.** The refactoring workflow operates exclusively on files tracked by git. Untracked files and directories must never be modified or deleted — their loss could be irreversible. This boundary is non-negotiable regardless of scope setting.

**If user specifies scope:** Respect that scope (directory, files, module). Pass scope constraint to all spawned agents.

2. Select Aggression Ceiling

**Ask the user:** "How aggressive should refactoring be?"

Present these options:

• **Maximum**: Attempt all improvements, including aggressive changes (removing legacy code with unclear purpose, consolidating similar-but-not-identical behavior)
• **High**: Go up to MODERATE changes (cross-module DRY, removing abstraction layers, splitting files into focused modules) but skip aggressive changes
• **Low**: Only SAFEST and SAFE changes (formatters, linters, dead code, simple DRY, pruning single-use indirection, reducing stutter)
• **Let's discuss**: Talk through the situation to determine the right level

The workflow still proceeds from least aggressive to more aggressive - this setting determines how far up the ladder to climb before stopping.

3. Gather QA Instructions

**Ask the user:** "Are there any special verification steps for the QA agent? For example: visual checks, manual testing commands, specific scenarios to validate."

**If provided:** Pass these instructions to the QA agent on every verification cycle, in addition to standard test suite execution.

**Examples of custom QA instructions:**

• "After each change, start the app, take a screenshot, and verify it renders correctly"
• "Run `make demo` and check that output matches expected behavior"
• "Hit the `/health` endpoint and verify 200 response"
• "Verify the CLI still produces valid output for `./tool --help`"

**If none provided:** QA agent runs standard verification (test suite, linters, formatters).

4. Aggression Philosophy

**Always make the least aggressive change available, up to the user's chosen ceiling (step 2).**

The `swe-code-reviewer` agent returns recommendations organized by risk level: **SAFEST → SAFE → MODERATE → AGGRESSIVE**. These aren't gates to pass through sequentially. Instead:

• Each pass, prefer the least aggressive changes available
• More aggressive changes naturally "bubble up" as gentler options are exhausted
• Stop when reaching the user's ceiling (e.g., if ceiling is High/MODERATE, skip AGGRESSIVE recommendations)
• Earlier refactorings may unlock new gentle changes (rescan catches these)

5. Iterative Refactoring Loop

For each iteration:

5a. Scan for Opportunities

**Spawn fresh `swe-code-reviewer` agent:**

• Agent performs FULL scan across all aggression levels
• Pass scope if user specified one
• Agent returns structured recommendations organized by risk level
• Fresh instance each pass (context management)

**Why full scan every time:**

• Refactoring creates new opportunities (consolidating duplicates may reveal higher-order patterns)
• Cascading improvements are the goal
• Fresh scan catches what previous changes unlocked

**Prompt the agent with:**

Scan for ALL refactoring opportunities across all aggression levels.
Scope: [entire codebase | user-specified scope]
Return recommendations organized by risk level (SAFEST → AGGRESSIVE).
Prioritize changes that produce RED diffs (net code reduction) while improving clarity.

**Orchestrator selects least aggressive changes:**

• From the