export default refactor-code-readme

name	refactor-code-readme
description	This skill should be used when the user asks "refactor code", "improve code quality", "use refactor plugin", "run /refactor", or needs guidance on automated iterative code refactoring with test coverage, architecture review, and clean code improvements.
version	1.0.0

Getting Started with Refactor Plugin

Purpose

Understand and use the Refactor plugin - an automated system that orchestrates three specialized AI agents to systematically improve code quality through iterative test-driven refactoring.

When to Use This Skill

Use this skill when:

• Learning how to use /refactor command
• Understanding the refactoring workflow
• Interpreting quality scores
• Planning refactoring scope
• Troubleshooting refactoring issues

Overview

The Refactor plugin systematically improves code quality while preserving functionality using three specialized agents:

• Test Agent: Ensures comprehensive test coverage
• Architect Agent: Reviews and plans improvements
• Code Agent: Implements clean code changes

Quick Start

# Refactor entire codebase
/refactor

# Refactor specific directory
/refactor src/utils/

# Refactor specific file
/refactor src/app.ts

# Refactor by description
/refactor "authentication logic"

The 7-Step Workflow

The plugin follows this rigorous process, iterating 3 times:

Step 1: Ensure Test Coverage

Test agent establishes comprehensive test baseline:

• Analyzes current coverage
• Identifies critical gaps
• Writes missing test cases
• Runs all tests to verify pass
• Reports coverage status

Goal: Production-quality coverage (typically 80%+)

Step 2: Architecture Review

Architect agent examines code quality (repeats each iteration):

• Identifies structural improvements
• Finds code duplication
• Reviews naming and clarity
• Checks separation of concerns
• Evaluates design patterns
• Assesses complexity
• Reviews dependencies

Output: Prioritized optimization list with impact/effort ratings

Step 3: Implement Top 3 Optimizations

Code agent carefully implements improvements:

• Makes incremental, safe changes
• Preserves all functionality
• Applies clean code principles
• Self-reviews each change
• Documents modifications

Principles: Meaningful names, small functions, single responsibility, DRY, appropriate abstraction

Step 4: Test Validation

Test agent validates changes:

• Executes full test suite
• Reports pass/fail status
• Provides detailed failure analysis

Step 5: Fix Failures

If tests fail, code agent:

• Analyzes root causes
• Implements targeted fixes
• Preserves refactoring improvements
• Returns to step 4 for re-validation

Step 6: Iteration Control

System tracks progress:

• Completes 3 full refactoring cycles
• Each iteration builds on previous
• Progressive refinement ensures thorough optimization

Step 7: Final Assessment

Architect agent produces comprehensive report:

• Clean Code Score (1-10): Readability, simplicity, maintainability
• Architecture Perfection Score (1-10): Design quality, SOLID principles
• Improvement Summary: Changes across iterations
• Remaining Issues: Future improvements
• Recommendations: Maintenance guidelines

Report saved as: refactor-result-{timestamp}.md

Understanding Quality Scores

Clean Code Score (1-10)

• 9-10: Exemplary - clear, simple, maintainable
• 7-8: Good with minor improvements needed
• 5-6: Acceptable but needs notable work
• 3-4: Poor with significant issues
• 1-2: Very poor, major refactoring needed

Evaluates: Naming, function size, DRY, comments, error handling, formatting

Architecture Perfection Score (1-10)

• 9-10: Excellent architecture, best practices
• 7-8: Good design, minor concerns
• 5-6: Acceptable, some issues
• 3-4: Poor, needs significant redesign
• 1-2: Very poor, major problems

Evaluates: SOLID principles, coupling/cohesion, abstraction, testability, extensibility

The Three Agents

Test Agent

Role: Quality assurance through testing

Capabilities:

• Coverage analysis
• Test case generation
• Test execution
• Failure diagnosis

Tools: Glob, Grep, Read, Write, Edit, Bash, TodoWrite

Architect Agent

Role: Design and architecture analysis

Capabilities:

• Code structure review
• Pattern identification
• Optimization planning
• Quality scoring

Tools: Glob, Grep, Read, TodoWrite, WebFetch

Code Agent

Role: Implementation of refactoring

Capabilities:

• Clean code refactoring
• Safe incremental changes
• Test failure fixing
• Best practice application

Tools: Glob, Grep, Read, Write, Edit, TodoWrite

Use Cases

When to Use Refactor

✅ Good for:

• Legacy code modernization
• Low test coverage improvement
• Known quality issues
• Pre-feature preparation
• Technical debt reduction
• Post-implementation cleanup
• Code review follow-up

❌ Not suitable for:

• Adding new features (functionality changes)
• Quick fixes during incidents
• No tests + no test framework
• Experimental/prototype code
• Code scheduled for deletion

Examples

Example 1: Full Codebase

/refactor

Process:

1. Analyzes entire codebase test coverage
2. Adds missing tests across all modules
3. Performs 3 iterations of review and optimization
4. Generates comprehensive quality report

Duration: ~30-60 minutes (size-dependent)

Example 2: Specific Module

/refactor src/services/payment/

Process:

1. Focuses on payment service only
2. Ensures payment logic well-tested
3. Optimizes payment service architecture
4. Produces targeted improvement report

Duration: ~10-20 minutes

Example 3: Single File

/refactor src/utils/validators.ts

Process:

1. Tests only validators.ts
2. Refactors validator functions
3. Reports on validator code quality

Duration: ~5-10 minutes

Best Practices

Before Refactoring

1. Commit work: Ensure clean git state
2. Set expectations: Large codebases take time
3. Review scope: Be specific if targeting subset

During Refactoring

1. Be patient: Quality takes time
2. Monitor progress: Watch iteration updates
3. Stay available: May need input on ambiguities

After Refactoring

1. Review report: Read refactor-result-{timestamp}.md
2. Check scores: Understand quality improvements
3. Review changes: Use git diff to see modifications
4. Run manual tests: Verify in development environment
5. Plan follow-up: Address remaining issues if needed

Configuration

Current defaults (hardcoded, designed for future configurability):

• Max Iterations: 3
• Optimizations per Iteration: Top 3
• Test Coverage Target: Production quality (typically 80%+)

Common Issues

Tests Keep Failing

Issue: Tests fail repeatedly after fixes

Solutions:

• Review test failure patterns
• Check for hidden dependencies
• Ensure test environment properly configured
• Run /refactor on smaller scope first

Iteration Takes Too Long

Issue: Each iteration very slow

Solutions:

• Reduce scope (specific files/directories)
• Ensure fast test suite (split out slow tests)
• Check for performance bottlenecks

Scores Lower Than Expected

Issue: Quality scores don't meet expectations

Solutions:

• Review detailed assessment in report
• Address critical issues identified
• Consider additional refactoring cycles
• Some codebases need multiple sessions

Agent Gets Stuck

Issue: Agent doesn't complete task

Solutions:

• Check agent progress output
• May need to cancel and restart with smaller scope
• Report if it's a bug in agent instructions

FAQ

Q: Will this change functionality? A: No. Refactoring explicitly preserves all functionality. Only quality and structure improve.

Q: How long does it take? A: Depends on scope:

• Single file: 5-10 minutes
• Module: 10-20 minutes
• Full codebase: 30-60 minutes

Q: Can I stop mid-refactor? A: Yes, but progress is lost. Better to start with smaller scope.

Q: Do I need to review every change? A: Recommended. While agents are thorough, human review is valuable.

Q: What if project has no tests? A: Test agent will create them in step 1.

Q: Can I run on production code? A: Only with proper review and deployment processes. Always review changes first.

Q: What languages/frameworks supported? A: All languages. Agents adapt to project's testing framework and conventions.

Q: Can I customize iteration count? A: Currently fixed at 3, designed for future configurability.

Key Features

Safety First

• No functionality changes
• Test-driven approach
• Iterative validation prevents regressions

Comprehensive Coverage

• Automatic test generation
• Edge case detection
• Coverage metrics reporting

Architecture Excellence

• SOLID principles evaluation
• Prioritized improvements (impact/effort)
• Objective quality scoring

Clean Code Implementation

• Focused improvements (top 3 per iteration)
• Progressive refinement (3 iterations)
• Proven refactoring patterns

Detailed Reporting

• Iteration summaries
• Comprehensive final assessment
• Actionable insights

Quick Reference

Command: /refactor [path] Duration: 5-60 minutes (scope-dependent) Iterations: 3 (fixed) Optimizations: Top 3 per iteration Report: refactor-result-{timestamp}.md Scores: Clean Code (1-10), Architecture (1-10)

Learn More

• Clean Code by Robert C. Martin
• Refactoring by Martin Fowler
• SOLID Principles
• Design Patterns

Additional Resources

Reference Files

For detailed guidance:

• references/workflow-details.md - Step-by-step workflow explanation
• references/agent-capabilities.md - Detailed agent documentation
• references/best-practices.md - Advanced refactoring strategies

Use the Refactor plugin to systematically improve code quality through automated, test-driven refactoring.