Refactoring Executor
Overview
Safely execute refactoring based on discovery reports using test-first verification and incremental steps. This skill automates/guides the refactoring process with continuous validation, metric tracking, and rollback capabilities to ensure zero regression.
When to Use This Skill
Invoke this skill in the following scenarios:
- Post-Discovery Refactoring - After generating a refactoring-discovery report, execute recommended changes
- Test-First Code Improvement - When refactoring requires validation at each step
- Safe Incremental Refactoring - For complex refactoring that needs small, verifiable steps
- Metric-Tracked Improvements - When you need before/after metrics for refactoring effectiveness
Prerequisites
Required Tools
- TypeScript: tsc, ts-node
- Testing: vitest (or jest)
- Linting: eslint
- Optional: ts-morph (for automated AST-based refactoring)
Input Requirements
- Refactoring discovery report (markdown format)
- All tests passing (green baseline)
- Clean git working directory (for rollback capability)
Core Capabilities
1. Report-Driven Execution
Parse refactoring discovery reports and execute recommended changes:
- Select target issue by priority
- Generate execution plan with step-by-step actions
- Validate feasibility and estimate effort
2. Test-First Verification
Ensure safety through continuous testing:
- Verify baseline (all tests pass before starting)
- Add characterization tests for missing coverage
- Run tests after each incremental change
- Validate types, lints, and performance metrics
3. Incremental Safe Steps
Support major refactoring patterns:
- Extract Method/Function
- Extract Class/Module
- Move Method/Field
- Rename Symbol
- Introduce Parameter Object
- Replace Conditional with Polymorphism
- Encapsulate Field/Collection
- Split Phase
4. Execution Logging
Track all changes with detailed logs:
- Before/after metrics (test time, bundle size, warnings)
- Each step's validation results
- Rollback points and procedures
- Decision rationale for each change
Safety Principles
Never Break Tests
- All tests must stay green throughout refactoring
- If a test fails, immediately revert the last change
- Investigate failure cause before proceeding
Small Steps, Frequent Validation
- One intent per change (rename → update usages → delete dead code)
- Commit after each successful validation
- Keep diffs reviewable and meaningful
Characterization Tests First
- Add tests to lock down existing behavior before structural changes
- Cover edge cases and invariants
- Use snapshot tests for complex outputs
Preserve Contracts
- Maintain existing API contracts
- Keep non-functional requirements (performance, security)
- Document any intentional breaking changes
Type-Driven Safety
- Use TypeScript's type system as a safety net
- Enable strict mode (strictNullChecks, noImplicitAny)
- Verify no type errors after each step
Workflow
6-Stage Execution Process
Stage 1: Parse Report and Select Target
Inputs: Refactoring discovery report (markdown)
Actions:
- Parse report to extract issues, priorities, and recommendations
- Ask user to select target issue (or auto-select highest priority)
- Analyze dependencies and affected files
- Verify no scope conflicts or circular dependencies
Outputs:
- Selected issue summary
- Affected file list
- Dependency graph
Safety Checkpoint:
Stage 2: Pre-Refactoring Validation
Actions:
- Run full test suite and verify all pass
- Run type checker (
tsc --noEmit)
- Run linter (
eslint)
- Capture baseline metrics:
- Test execution time
- Test count
- Type error count (should be 0)
- Lint warning count
- Bundle size (if applicable)
- Performance benchmarks (if available)
Outputs:
execution-plan.md (from assets/execution-plan-template.md)
- Baseline metrics JSON
Safety Checkpoint:
Rollback: If validation fails, stop and report issues to user
Stage 3: Add Characterization Tests
Actions:
- Identify code paths lacking test coverage
- Add characterization tests using
assets/characterization-test-template.md:
- Given: Initial state
- When: Action/behavior
- Then: Expected output (capture current behavior)
- Run new tests to verify they pass
- Commit characterization tests separately
Outputs:
- New test files (e.g.,
*.characterization.test.ts)
- Test coverage report
Safety Checkpoint:
Rollback: Characterization tests are additive; if they fail, it indicates existing bugs
Stage 4: Execute Incremental Refactoring
Actions:
- Break refactoring into smallest possible steps
- For each step:
a. Apply one refactoring pattern (see
references/refactoring-patterns.md)
b. Run verification (see Stage 5)
c. If verification fails, rollback and adjust
d. If verification passes, commit with descriptive message
e. Log step results in execution-log.md
Supported Patterns (detailed in references/refactoring-patterns.md):
- Extract Method: Extract code block into named function
- Extract Class: Split class into focused classes
- Move Method: Relocate method to appropriate class
- Rename Symbol: Rename for clarity (auto-update references)
- Introduce Parameter Object: Group related parameters
- Replace Conditional with Polymorphism: Convert switch/if-else to strategy pattern
- Encapsulate Field: Add getters/setters for direct field access
- Split Phase: Separate computation from side effects
Outputs:
- Modified source files
- Git commits (one per step)
- Execution log entries
Safety Checkpoint (per step):
Rollback (per step):
git reset --hard HEAD~1 # Revert last commit
# Or use git stash if uncommitted
Stage 5: Step Verification
Actions (after each incremental change):
- Run affected tests:
pnpm vitest --run --reporter=json --filter <scope>
- Run type checker:
pnpm tsc --noEmit
- Run linter:
pnpm eslint --format=json <affected-files>
- Optional: Run performance benchmarks
- Capture metrics and compare to baseline
- Log results to
execution-log.md
Tool Integration (see references/tooling-playbook.md):
scripts/verify-step.sh: Automated verification script
scripts/ts-morph-refactors.ts: AST-based refactoring helpers
Outputs:
- Test results (JSON)
- Type checker output
- Lint results
- Step metrics
Safety Checkpoint:
Rollback: If any check fails, revert the step and document failure cause
Stage 6: Post-Refactoring Report
Actions:
- Run full test suite and capture final metrics
- Compare final vs. baseline metrics
- Generate execution log using
assets/execution-log-template.md:
- Summary of changes
- Steps taken with validation results
- Before/after metrics comparison
- Remaining work (if any)
- Lessons learned
- Update refactoring discovery report with completion status
- Create pull request with:
- Link to execution log
- Metric improvements
- Testing evidence
Outputs:
execution-log.md (completed)
- Metrics comparison table
- Pull request description
Safety Checkpoint:
Example Usage Scenarios
Scenario 1: Extract Large Method
User: "Execute refactoring for ComparisonRunner.run() method (667 LOC)"
Process:
- Parse: Load refactoring-discovery report, select ComparisonRunner issue
- Validate: Run tests (✅), capture baseline (test time: 12.5s, CC: 45)
- Characterization Tests: Add tests for pairing logic, summary generation, statistical analysis
- Step 1: Extract pairing logic →
PairingStrategy interface
- Verify: Tests pass ✅, Types valid ✅, Lint clean ✅
- Commit: "refactor: extract pairing logic to PairingStrategy interface"
- Step 2: Extract summary generation →
SummaryGenerator class
- Verify: Tests pass ✅, Types valid ✅, Lint clean ✅
- Commit: "refactor: extract summary generation to SummaryGenerator"
- Step 3: Extract statistical analysis →
StatisticalAnalyzer class
- Verify: Tests pass ✅, Types valid ✅, Lint clean ✅
- Commit: "refactor: extract statistical analysis to StatisticalAnalyzer"
- Step 4: Refactor ComparisonRunner to use extracted components
- Verify: Tests pass ✅, Types valid ✅, Lint clean ✅
- Commit: "refactor: simplify ComparisonRunner using extracted components"
- Report: Generate execution log
- Before: 667 LOC, CC 45
- After: 150 LOC (runner), 100 LOC (pairing), 150 LOC (summary), 100 LOC (analyzer)
- CC reduced: 45 → 8 (runner), 6 (pairing), 8 (summary), 6 (analyzer)
- Tests: 100% pass, no regressions
- Time: 3.5 hours actual
Scenario 2: Split Module by Category
User: "Execute refactoring for metrics/index.ts (419 LOC, 3 categories)"
Process:
- Parse: Load report, select metrics module issue
- Validate: Baseline captured ✅
- Characterization Tests: All metrics already well-tested ✅
- Step 1: Create
metrics/ranking.ts and move ranking metrics
- Verify: Tests pass ✅
- Commit: "refactor: extract ranking metrics to ranking.ts"
- Step 2: Create
metrics/latency.ts and move latency metrics
- Verify: Tests pass ✅
- Commit: "refactor: extract latency metrics to latency.ts"
- Step 3: Create
metrics/events.ts and move event metrics
- Verify: Tests pass ✅
- Commit: "refactor: extract event metrics to events.ts"
- Step 4: Update
metrics/index.ts to barrel export
- Verify: Tests pass ✅, no breaking changes ✅
- Commit: "refactor: convert metrics/index.ts to barrel export"
- Report: Execution log shows clean split, backward compatible
Reference Materials
Refactoring Patterns (references/refactoring-patterns.md)
Detailed step-by-step guides for each supported pattern:
- Prerequisites and applicability conditions
- Incremental transformation steps
- Type safety checklist
- Rollback procedures
- Common pitfalls and solutions
Load this file when executing specific refactoring patterns.
Safety Checkpoints (references/safety-checkpoints.md)
Critical checkpoints throughout the refactoring process:
- Pre-refactoring validation checklist
- Per-step verification requirements
- Rollback triggers and procedures
- Metric threshold definitions
Load this file to ensure all safety gates are enforced.
Tooling Playbook (references/tooling-playbook.md)
Tool integration and usage examples:
- ts-morph scripts for AST-based refactoring
- vitest/jest command examples and failure diagnostics
- eslint integration with JSON output parsing
- tsc type checking with targeted file validation
Load this file when using automated tooling for refactoring.
Best Practices
DO:
- ✅ Always start with green tests
- ✅ Add characterization tests before structural changes
- ✅ Make smallest possible changes
- ✅ Commit after each successful validation
- ✅ Capture metrics before and after
- ✅ Document decisions in execution log
- ✅ Use TypeScript's type system as safety net
- ✅ Rollback immediately on failure
DON'T:
- ❌ Skip test validation
- ❌ Make multiple changes before verifying
- ❌ Ignore type errors
- ❌ Refactor without characterization tests
- ❌ Proceed with failing tests
- ❌ Forget to capture baseline metrics
- ❌ Skip documentation of changes
Integration with Development Workflow
With Refactoring Discovery
- Run refactoring-discovery to generate report
- Review report and prioritize issues
- Use refactoring-executor to implement top-priority changes
- Re-run refactoring-discovery to verify improvements
With Pull Requests
- Include execution log in PR description
- Link to refactoring discovery report
- Show before/after metrics
- Highlight test coverage improvements
With CI/CD
- Run verification script in CI pipeline
- Track metrics over time
- Fail builds on metric regressions
- Generate trend reports
Resources Summary
References (Load into context as needed)
references/refactoring-patterns.md - Step-by-step guides for each pattern
references/safety-checkpoints.md - Critical validation checkpoints
references/tooling-playbook.md - Tool integration examples
Assets (Use in execution)
assets/execution-plan-template.md - Plan template with steps and metrics
assets/execution-log-template.md - Log template for tracking execution
assets/characterization-test-template.md - Template for adding behavior tests
Scripts (Automation helpers)
scripts/parse-report.ts - Parse refactoring discovery reports
scripts/ts-morph-refactors.ts - AST-based refactoring utilities
scripts/verify-step.sh - Automated step verification
These resources ensure safe, documented, and verifiable refactoring execution.