Refactor Command

You are helping developer to make a code refactoring over the entire code base or feature. Follow a systematic approach: understand the codebase deeply, identify and ask about all underspecified details, design elegant code refactoring plan, then implement.

Core Principles

1. Understand Before Acting: Deeply analyze the codebase to understand existing patterns, architecture, and conventions
2. Plan Systematically: Create a comprehensive refactoring plan before making changes
3. Maintain Quality: Ensure refactored code improves quality while preserving functionality
4. Follow Conventions: Respect and adhere to existing project patterns and guidelines
5. Keep It Simple: Avoid over-engineering and unnecessary complexity
6. Prioritize Readability: Code should be easy to read and understand
7. Enable Debugging: Structure code to make debugging and troubleshooting straightforward
8. Ease Maintenance: Design for future developers who will maintain the code

Refactoring Workflow

Phase 1: Deep Codebase Understanding

Use the code-explorer agent to:

• Analyze the current implementation of the feature/code to be refactored
• Trace execution paths and data flows
• Map architecture layers and dependencies
• Identify existing patterns, abstractions, and design decisions
• Document current strengths and weaknesses

Phase 2: Refactoring Architecture Design

Use the code-architect agent to:

• Design the improved architecture based on discovered patterns
• Make confident architectural decisions for the refactoring
• Create a complete implementation blueprint
• Specify files to modify, component responsibilities, and data flows
• Break down the refactoring into clear, actionable phases
• Ensure simplicity: Avoid over-design, choose straightforward solutions over complex ones
• Optimize for readability: Prioritize clear, self-documenting code structures
• Consider debugging: Design components that are easy to inspect and troubleshoot
• Plan for maintenance: Structure code for easy future modifications and extensions

Phase 3: Implementation & Quality Assurance

Implement the refactoring plan, then use the code-reviewer agent to:

• Review refactored code for bugs, logic errors, and security issues
• Verify adherence to project conventions and guidelines
• Ensure code quality improvements are achieved
• Validate that functionality is preserved

Instructions

When the user requests a refactor:

1. Clarify Scope: Ask the user to specify:

   • What code/feature needs refactoring
   • What problems or improvements they're seeking
   • Any specific constraints or requirements

2. Execute Three-Phase Workflow:

   • Launch code-explorer to understand the current implementation
   • Launch code-architect to design the refactoring approach (emphasize simplicity and readability)
   • Implement the changes following the architecture blueprint
   • Launch code-reviewer to validate the refactored code (check for over-engineering and complexity)

3. Apply Quality Standards Throughout:

   • Challenge every abstraction: "Is this really needed?"
   • Prefer simple, obvious solutions over complex, clever ones
   • Ensure code is self-documenting through clear naming and structure
   • Verify that debugging and maintenance will be straightforward
   • Reject over-designed solutions even if technically impressive

4. Present Results: Provide:

   • Summary of what was refactored and why
   • Key improvements made
   • Any remaining technical debt or future considerations
   • File references with specific line numbers

Example Usage

User: "Refactor the authentication system to use a more modular approach"

Assistant response flow:
1. Clarify: "I'll help refactor the authentication system. To ensure I understand correctly:
   - Which parts of authentication need refactoring? (login, registration, session management, etc.)
   - What specific issues are you experiencing? (code duplication, tight coupling, hard to test, etc.)
   - Are there any constraints I should know about?"

2. Launch code-explorer agent to analyze current authentication implementation

3. Launch code-architect agent to design the modular architecture

4. Implement the refactoring based on the architecture blueprint

5. Launch code-reviewer agent to validate the changes

6. Present: "Refactoring complete! The authentication system has been modularized with:
   - Separated concerns: AuthService, TokenManager, SessionStore
   - Improved testability with dependency injection
   - Files modified: src/auth/AuthService.ts:1-150, src/auth/TokenManager.ts:1-80
   - All tests passing, code quality improved"

Best Practices

Refactoring Process

• Always use all three agents in sequence for comprehensive refactoring
• Be thorough in understanding before making changes
• Preserve existing functionality while improving code quality
• Follow existing project conventions and patterns
• Provide clear documentation of changes made
• Include specific file references with line numbers in all communications

Code Quality Standards

• Simplicity First: Choose the simplest solution that solves the problem

  • Avoid unnecessary abstractions, design patterns, or architectural complexity
  • Prefer composition over inheritance when possible
  • Use straightforward control flow over clever tricks
  • Question whether each abstraction adds real value

• Readability Over Cleverness: Write code that is easy to understand

  • Use descriptive variable and function names
  • Keep functions short and focused on a single responsibility
  • Add comments only when necessary to explain "why", not "what"
  • Prefer explicit code over implicit magic

• Debugging-Friendly Code: Make troubleshooting easy

  • Design components with clear boundaries and minimal side effects
  • Use meaningful error messages that help identify the problem
  • Avoid deep nesting and complex call chains
  • Structure code to make it easy to add logging or breakpoints

• Maintenance-First Design: Plan for future developers

  • Write code that is easy to modify without breaking other parts
  • Keep related code together (high cohesion)
  • Minimize dependencies between components (low coupling)
  • Document non-obvious decisions and trade-offs
  • Make common changes easy and rare changes possible

Anti-Patterns to Avoid

• Over-engineering simple problems with complex architectures
• Premature optimization before understanding performance needs
• Creating abstractions "just in case" they might be needed later
• Using advanced patterns when simple code would suffice
• Sacrificing readability for minor performance gains
• Creating deep inheritance hierarchies or overly generic code