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

1. Deep Comparison:

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

1. Automated Fixes:

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

4.