--- description: Metrics-driven code quality improvement with behavior preservation --- ## User Input ```text $ARGUMENTS ``` You **MUST** consider the user input before proceeding (if not empty). ## Goal Execute metrics-driven refactoring workflow to improve code quality while preserving behavior. **Key Principles**: 1. **Metrics First**: Establish baseline before refactoring 2. **Behavior Preservation**: No functional changes 3. **Testable**: Verify identical behavior before/after 4. **Measurable Improvement**: Quantify quality gains 5. **Incremental**: Small, safe refactoring steps **Refactoring Types**: Extract function/module, reduce complexity, eliminate duplication, improve naming, optimize performance **Coverage**: Addresses ~10% of development work (quality improvement) --- ## Smart Integration ```bash SPECSWARM_INSTALLED=$(claude plugin list | grep -q "specswarm" && echo "true" || echo "false") SPECTEST_INSTALLED=$(claude plugin list | grep -q "spectest" && echo "true" || echo "false") if [ "$SPECTEST_INSTALLED" = "true" ]; then EXECUTION_MODE="parallel" ENABLE_HOOKS=true ENABLE_METRICS=true echo "🎯 SpecTest detected (parallel execution, hooks, metrics enabled)" elif [ "$SPECSWARM_INSTALLED" = "true" ]; then ENABLE_TECH_VALIDATION=true echo "🎯 SpecSwarm detected (tech stack enforcement enabled)" fi ``` --- ## Execution Steps ### 1. Discover Refactor Context ```bash REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) REFACTOR_NUM=$(echo "$CURRENT_BRANCH" | grep -oE 'refactor/([0-9]{3})' | grep -oE '[0-9]{3}') if [ -z "$REFACTOR_NUM" ]; then echo "♻️ Refactor Workflow" echo "Provide refactor number:" read -p "Refactor number: " REFACTOR_NUM REFACTOR_NUM=$(printf "%03d" $REFACTOR_NUM) fi # Source features location helper SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PLUGIN_DIR="$(dirname "$SCRIPT_DIR")" source "$PLUGIN_DIR/lib/features-location.sh" # Initialize features directory ensure_features_dir "$REPO_ROOT" FEATURE_DIR="${FEATURES_DIR}/${REFACTOR_NUM}-refactor" mkdir -p "$FEATURE_DIR" REFACTOR_SPEC="${FEATURE_DIR}/refactor.md" BASELINE_METRICS="${FEATURE_DIR}/baseline-metrics.md" TASKS_FILE="${FEATURE_DIR}/tasks.md" ``` --- ### 2. Establish Baseline Metrics Analyze target code and establish baseline: ```markdown # Baseline Metrics: Refactor ${REFACTOR_NUM} **Target**: [File/module/function to refactor] **Analysis Date**: YYYY-MM-DD --- ## Code Metrics ### Complexity Metrics - **Cyclomatic Complexity**: [N] (target: <10) - **Cognitive Complexity**: [N] (target: <15) - **Nesting Depth**: [N] (target: <4) - **Function Length**: [N lines] (target: <50) ### Quality Metrics - **Code Duplication**: [N%] (target: <3%) - **Test Coverage**: [N%] (target: >80%) - **Maintainability Index**: [N/100] (target: >65) ### Performance Metrics (if applicable) - **Execution Time**: [duration] - **Memory Usage**: [MB] - **Database Queries**: [N] --- ## Identified Issues | Issue | Severity | Metric | Current | Target | |-------|----------|--------|---------|--------| | [Issue 1] | High | [Metric] | [Value] | [Value] | | [Issue 2] | Medium | [Metric] | [Value] | [Value] | --- ## Refactoring Opportunities ### Opportunity 1: [Type - e.g., Extract Function] **Location**: [file:line] **Issue**: [What's wrong] **Approach**: [How to refactor] **Expected Improvement**: [Metric improvement] [Repeat for each opportunity] --- ## Behavior Preservation Tests **Existing Tests**: [N tests] **Coverage**: [N%] **Additional Tests Needed**: [Y/N - list if yes] **Test Strategy**: - Run full test suite before refactoring - Verify 100% pass rate - Run same tests after each refactor step - Verify identical results --- ## Success Criteria **Metrics Improvement Targets**: - Complexity: [current] → [target] - Duplication: [current] → [target] - Test Coverage: [current] → [target] - Maintainability: [current] → [target] **Non-Negotiables**: - ✅ All tests pass (before and after) - ✅ No functional changes - ✅ No performance regression ``` Write to `$BASELINE_METRICS`. --- ### 3. Create Refactor Specification ```markdown # Refactor ${REFACTOR_NUM}: [Title] **Status**: Active **Created**: YYYY-MM-DD **Baseline Metrics**: ${BASELINE_METRICS} --- ## Refactoring Goal **What We're Improving**: [Brief description] **Why**: [Motivation] - Pain point 1 - Pain point 2 **Type**: [Extract Function/Reduce Complexity/Eliminate Duplication/Improve Naming/Optimize Performance] --- ## Target Code **Location**: [file:line range] **Current Issues**: - Issue 1 - Issue 2 --- ## Refactoring Plan ### Step 1: [Refactor Action] **What**: [Description] **Files**: [list] **Validation**: [How to verify] ### Step 2: [Refactor Action] [Repeat pattern] --- ## Behavior Preservation **Critical**: No functional changes allowed **Validation Strategy**: 1. Capture test suite results (before) 2. Apply refactoring step 3. Run test suite (after) 4. Compare results (must be identical) 5. Repeat for each step --- ## Expected Improvements **Metrics**: | Metric | Before | After | Improvement | |--------|--------|-------|-------------| | Complexity | [N] | [Target] | [%] | | Duplication | [N%] | [Target] | [%] | | Maintainability | [N] | [Target] | [%] | --- ## Risks | Risk | Mitigation | |------|------------| | [Risk 1] | [Mitigation] | --- ## Tech Stack Compliance ${TECH_STACK_VALIDATION} ``` Write to `$REFACTOR_SPEC`. --- ### 4. Generate Tasks ```markdown # Tasks: Refactor ${REFACTOR_NUM} **Workflow**: Refactor (Metrics-Driven, Behavior-Preserving) --- ## Phase 1: Baseline Establishment ### T001: Establish Baseline Metrics **Description**: Run code analysis tools, capture metrics **Validation**: Baseline documented in ${BASELINE_METRICS} ### T002: Run Full Test Suite (Baseline) **Description**: Capture test results before refactoring **Expected**: 100% pass rate (or document failures) **Parallel**: No --- ## Phase 2: Incremental Refactoring [For each refactoring step, create task sequence:] ### T003: Refactor Step 1 - [Description] **Description**: [What's changing] **Files**: [list] **Validation**: Code compiles, no functional changes **Parallel**: No (incremental steps) ### T004: Test Step 1 **Description**: Run test suite after step 1 **Expected**: Identical results to baseline **Parallel**: No (depends on T003) [Repeat T00N/T00N+1 pattern for each refactor step] --- ## Phase 3: Validation and Metrics ### T00N: Run Full Test Suite (Final) **Description**: Verify all tests still pass **Expected**: 100% pass rate, identical to baseline ### T00N+1: Measure Final Metrics **Description**: Capture metrics after refactoring **Expected**: Measurable improvement in target metrics **Parallel**: [P] ### T00N+2: Compare Metrics **Description**: Generate before/after comparison **Expected**: Improvements meet success criteria **Parallel**: No --- ## Summary **Total Tasks**: [N] **Refactoring Steps**: [N] **Estimated Time**: [time] **Success Criteria**: - ✅ All tests pass (identical results before/after) - ✅ Measurable metrics improvement - ✅ No functional changes - ✅ No performance regression ``` Write to `$TASKS_FILE`. --- ### 5. Execute Refactoring Workflow Execute tasks incrementally with test validation after each step: ``` ♻️ Executing Refactor Workflow Phase 1: Baseline Establishment T001: Establish Baseline Metrics [Analyze code, capture metrics] ✓ Baseline: Complexity=45, Duplication=12%, Maintainability=52 T002: Run Full Test Suite (Baseline) [Run tests] ✓ 247 tests passed Phase 2: Incremental Refactoring T003: Extract Function - processUserData [Apply refactoring] T004: Test Step 1 [Run tests] ✓ 247 tests passed (identical to baseline) [Repeat for each refactoring step] Phase 3: Validation and Metrics T00N: Run Full Test Suite (Final) ✓ 247 tests passed (100% identical to baseline) T00N+1: Measure Final Metrics ✓ Complexity=12 (was 45) - 73% improvement ✅ ✓ Duplication=2% (was 12%) - 83% improvement ✅ ✓ Maintainability=78 (was 52) - 50% improvement ✅ T00N+2: Compare Metrics ✓ All success criteria met ``` --- ## Final Output ``` ✅ Refactor Workflow Complete - Refactor ${REFACTOR_NUM} 📊 Metrics Improvement: | Metric | Before | After | Improvement | |--------|--------|-------|-------------| | Complexity | [N] | [N] | [%] ✅ | | Duplication | [N%] | [N%] | [%] ✅ | | Maintainability | [N] | [N] | [%] ✅ | ✅ Behavior Preservation: - All tests passed (before and after) - Identical test results - No functional changes - No performance regression ⏱️ Time to Refactor: ${DURATION} 📈 Next Steps: 1. Review: ${REFACTOR_SPEC} 2. Commit refactoring 3. Share metrics improvements with team ``` --- ## Operating Principles 1. **Metrics First**: Establish measurable baseline 2. **Incremental**: Small, safe refactoring steps 3. **Test After Each Step**: Verify behavior preservation 4. **Measurable**: Quantify quality improvements 5. **No Functional Changes**: Behavior must be identical 6. **Tech Compliance**: Validate against tech stack --- ## Success Criteria ✅ Baseline metrics established ✅ Incremental refactoring steps completed ✅ All tests pass (before and after) ✅ Identical test results (behavior preserved) ✅ Measurable metrics improvement ✅ No performance regression ✅ Tech stack compliant --- **Workflow Coverage**: Addresses ~10% of development work (quality improvement)