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 full scan, select the LEAST aggressive recommendations available
• Batch and implement those
• Rescan - previous changes may have unlocked new gentle options
• Aggressive changes naturally surface as gentler ones are exhausted
• If no recommendations at any level: workflow complete

Set aside user-decision items:

• Commented-out code: Do not implement. Collect findings across all passes.
• Informational findings (unused public APIs): Do not implement. Collect across all passes.
• Present both to the user in the completion summary (step 6).

5b. Plan Implementation

Review recommendations from scan. Group related changes into atomic batches.

Batching criteria:

• Changes to the same module/package
• Logically related refactorings (e.g., all DRY violations of the same pattern)
• Changes that must be done together to maintain consistency

For each batch, prepare:

• Clear list of changes to make
• Files affected
• Expected outcome (lines removed, patterns eliminated)
• Which SME agent is appropriate (based on language/framework)

5c. Implement Changes

Detect appropriate SME and spawn based on primary file type in batch:

• Go: swe-sme-golang
• Dockerfile: swe-sme-docker
• Makefile: swe-sme-makefile
• GraphQL: swe-sme-graphql
• Ansible: swe-sme-ansible
• Zig: swe-sme-zig
• TypeScript: swe-sme-typescript
• JavaScript: swe-sme-javascript
• HTML: swe-sme-html
• CSS: swe-sme-css

For languages without a dedicated SME (Python, Rust, etc.): implement directly as orchestrator, following language idioms and project conventions.

For mixed-language batches: split into per-language batches, or implement directly if changes are mechanical (e.g., dead code removal across file types).

Prompt the SME with:

Implement the following refactorings:
[List of specific changes from batch]

These changes should:
- Follow existing project conventions
- Maintain all existing behavior
- Result in net code reduction where possible

Report when complete.

SME implements and reports back.

5d. Verify Changes

Spawn qa-engineer agent:

• Run test suite
• Run linters/formatters
• Execute any custom QA instructions gathered in step 3
• Verify no regressions introduced
• Report pass/fail