9.6 KiB
9.6 KiB
description
| description |
|---|
| Metrics-driven code quality improvement with behavior preservation |
User Input
$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:
- Metrics First: Establish baseline before refactoring
- Behavior Preservation: No functional changes
- Testable: Verify identical behavior before/after
- Measurable Improvement: Quantify quality gains
- 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
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
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:
# 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
# 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
# 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
- Metrics First: Establish measurable baseline
- Incremental: Small, safe refactoring steps
- Test After Each Step: Verify behavior preservation
- Measurable: Quantify quality improvements
- No Functional Changes: Behavior must be identical
- 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)