/refactor

Intelligent Refactoring Engine

I'll help you restructure your code systematically - preserving functionality while improving structure, readability, and maintainability.

Arguments: `$ARGUMENTS` - files, directories, or refactoring scope

**KEY FEATURE: Built-in validation and refinement after EVERY change ensures nothing breaks and no code is left behind. The AI will automatically fix its own mistakes during the refactoring process.**

**SESSION FILES LOCATION: Always use refactor/ folder in current directory**

Session Intelligence

I'll maintain refactoring continuity across sessions:

**Session Files (in current project):**

• `refactor/plan.md` - Refactoring plan with progress tracking
• `refactor/state.json` - Current state and completed actions

**IMPORTANT:** The `refactor` folder is created in your CURRENT PROJECT directory. Use `refactor/` to access it.

**Auto-Detection:**

• If session exists: Resume from last checkpoint
• If no session: Create new refactoring plan
• Commands: `resume`, `continue`, `status`, `new`

**EXAMPLE OF CORRECT PATH USAGE:**

# CORRECT - looks in current project:
Read refactor/state.json
LS refactor

# WRONG - these will fail:
Read ../../../refactor/state.json
Read $HOME/.claude/refactor/state.json

Phase 1: Initial Setup & Analysis

Extended Thinking for Complex Refactoring

For complex refactoring scenarios, I'll use extended thinking to develop comprehensive strategies:

<think> When faced with complex architectural refactoring:

• Multi-step transformation paths that preserve functionality
• Risk mitigation strategies for each transformation
• Dependency graph analysis and update ordering
• Performance implications of different approaches
• Backwards compatibility requirements
• Testing strategies for validating each step

</think>

**Triggers for Extended Analysis:**

• Large-scale architectural changes
• Complex dependency untangling
• Performance-critical refactoring
• Legacy system modernization

**MANDATORY FIRST STEPS FOR SESSION CHECK:**

Step 1: Check for refactor directory in CURRENT directory
Command: LS refactor

Step 2: If refactor exists, read session files:
Command: Read refactor/state.json
Command: Read refactor/plan.md

DO NOT USE THESE WRONG PATHS:
- ../../../refactor/  (WRONG - goes up directories)
- $HOME/refactor/  (WRONG - home directory)
- ~/refactor/  (WRONG - home directory)

ONLY USE: refactor/ (current directory)

**CRITICAL:** The refactor folder is created in the CURRENT WORKING DIRECTORY where user is running the command. NOT in home, NOT in parent directories.

I'll examine your codebase to identify improvement opportunities:

**Analysis Focus:**

• Code complexity hotspots using **Grep** patterns
• Duplication detection across files
• Architecture inconsistencies
• Test coverage for safe refactoring
• Performance bottlenecks

**Smart Scoping:**

• If specific files provided: Focused analysis
• If directory provided: Recursive analysis
• If no arguments: Strategic project-wide scan

Phase 2: Refactoring Planning

Based on analysis, I'll create a structured plan:

**Refactoring Categories:**

• **Quick Wins**: Variable renames, method extractions
• **Structural**: Pattern applications, dependency improvements
• **Architectural**: Major reorganizations, module boundaries
• **Performance**: Algorithm optimizations, caching strategies

**Plan Structure:** I'll create a detailed plan in `refactor/plan.md`:

# Refactor Plan - [timestamp]

## Initial State Analysis
- **Current Architecture**: [description of existing patterns]
- **Problem Areas**: [specific issues found]
- **Dependencies**: [external/internal dependencies]
- **Test Coverage**: [current coverage %]

## Refactoring Tasks
[Prioritized list with risk levels]

## Validation Checklist
- [ ] All old patterns removed
- [ ] No broken imports
- [ ] All tests passing
- [ ] Build successful
- [ ] Type checking clean
- [ ] No orphaned code
- [ ] Documentation updated

## De-Para Mapping
| Before | After | Status |
|--------|-------|--------|
| OldService.method() | NewService.method() | Pending |
| /api/v1/* | /api/v2/* | Pending |

Phase 3: Incremental Execution

I'll apply refactorings systematically:

**Execution Order:** 1. Create git checkpoint for safety 2. Apply low-risk improvements first 3. Validate after each change 4. Progress to higher-impact refactorings 5. Update plan with completion status

**Continuous Validation & Refinement:** After EVERY refactoring change: 1. **Immediate Testing:**

• Run unit tests for modified files
• Execute integration tests if applicable
• Verify no test regressions

2. **Deep Comparison:**

• Compare function outputs before/after
• Validate API contracts maintained
• Check for missing edge cases
• Verify error handling preserved

3. **Automated Fixes:**

• Update broken imports automatically
• Fix reference errors
• Adjust type definitions
• Resolve linting issues

4. **Quality Gates:**

• STOP if tests fail - fix immediately
• STOP if behavior changes - investigate
• STOP if performance degrades - optimize
• Only proceed when 100% validated

5. **Continuous Refinement:**

• Re-scan for missed patterns
• Update all related files
• Clean up orphaned code
• Document breaking changes

Phase 4: Pattern Application

I'll apply consistent patterns throughout:

**Pattern Recognition:**

• Identify existing patterns in your code
• Detect anti-patterns to eliminate
• Apply design patterns where beneficial
• Maintain architectural consistency

**Code Improvements:**

• Extract duplicated code into utilities
• Simplify complex functions
• Improve naming for clarity
• Reduce coupling between modules

Phase 5: Quality Metrics

I'll track refactoring impact:

**Measurable Improvements:**

• Complexity reduction percentages
• Duplication elimination count
• Test coverage maintenance
• Performance benchmarks
• Code readability scores

C