Initial commit

2025-11-29 17:56:23 +08:00
commit 4292614d3a
9 changed files with 1320 additions and 0 deletions
--- a/commands/refactor-plan.md
+++ b/commands/refactor-plan.md
@@ -0,0 +1,249 @@
+# /specweave-core:refactor-plan
+
+Generate comprehensive refactoring plans with risk assessment, step-by-step execution, and rollback strategies.
+
+You are an expert software architect who plans safe, incremental refactoring strategies.
+
+## Your Task
+
+Create detailed refactoring plans that minimize risk while improving code quality.
+
+### 1. Refactoring Patterns
+
+**Extract Method**:
+```typescript
+// Before: Long function with multiple responsibilities
+function processOrder(order: Order) {
+  // 50 lines of validation
+  // 30 lines of calculation
+  // 40 lines of persistence
+}
+
+// After: Small, focused functions
+function processOrder(order: Order) {
+  validateOrder(order);
+  const total = calculateTotal(order);
+  saveOrder(order, total);
+}
+```
+
+**Extract Class**:
+```typescript
+// Before: God class
+class User {
+  // User properties
+  // Email sending logic
+  // Password hashing logic
+  // Notification logic
+}
+
+// After: Single responsibility
+class User { /* core user data */ }
+class EmailService { /* email logic */ }
+class PasswordHasher { /* password logic */ }
+class NotificationService { /* notifications */ }
+```
+
+**Replace Conditional with Polymorphism**:
+```typescript
+// Before: Switch statements
+function calculateShipping(type: string, weight: number) {
+  switch (type) {
+    case 'express': return weight * 5;
+    case 'standard': return weight * 2;
+    case 'economy': return weight * 1;
+  }
+}
+
+// After: Strategy pattern
+interface ShippingStrategy {
+  calculate(weight: number): number;
+}
+
+class ExpressShipping implements ShippingStrategy {
+  calculate(weight: number) { return weight * 5; }
+}
+```
+
+**Introduce Parameter Object**:
+```typescript
+// Before: Long parameter lists
+function createUser(name: string, email: string, age: number, address: string, phone: string)
+
+// After: Parameter object
+interface UserData {
+  name: string;
+  email: string;
+  age: number;
+  address: string;
+  phone: string;
+}
+
+function createUser(data: UserData)
+```
+
+### 2. Refactoring Plan Template
+
+```markdown
+## Refactoring Plan: Extract Payment Processing
+
+### Current State
+- 500-line PaymentController with mixed responsibilities
+- Tightly coupled to database layer
+- No unit tests (integration tests only)
+- Duplicate payment validation logic in 3 places
+
+### Target State
+- Payment domain services (validation, processing, reconciliation)
+- Repository pattern for data access
+- 80%+ unit test coverage
+- Single source of truth for validation
+
+### Risk Assessment
+**Risk Level**: Medium
+
+**Risks**:
+1. Breaking existing payment flows (HIGH IMPACT)
+2. Race conditions in concurrent payments (MEDIUM)
+3. Performance regression (LOW)
+
+**Mitigation**:
+1. Feature flag + parallel run (old + new code)
+2. Transaction isolation + row-level locking
+3. Performance testing before rollout
+
+### Prerequisites
+- [ ] 100% integration test coverage of current behavior
+- [ ] Performance baseline established
+- [ ] Database migrations prepared
+- [ ] Rollback plan documented
+- [ ] Team review and approval
+
+### Execution Steps (10 steps, 2 weeks)
+
+**Week 1: Preparation + Safe Extractions**
+
+**Step 1** (Day 1): Add comprehensive integration tests
+- Test all payment flows
+- Test error scenarios
+- Test edge cases (concurrent payments, retries)
+
+**Step 2** (Day 2): Extract validation logic
+- Create PaymentValidator class
+- Move validation from controller
+- Tests: unit tests for validator
+- **Safe**: Pure functions, no state changes
+
+**Step 3** (Day 3): Extract payment processing
+- Create PaymentProcessor service
+- Move core processing logic
+- Tests: unit tests with mocks
+- **Safe**: Existing controller calls new service
+
+**Week 2: Risky Changes + Rollout**
+
+**Step 7** (Day 8): Introduce repository pattern
+- Create PaymentRepository interface
+- Implement with existing DB calls
+- **Risk**: Data access changes
+- **Mitigation**: Feature flag, parallel run
+
+**Step 10** (Day 10): Final cutover
+- Enable new code for 100% traffic
+- Monitor for 48 hours
+- Remove old code if stable
+
+### Testing Strategy
+- Unit tests: 80%+ coverage
+- Integration tests: All payment flows
+- Load testing: 2x expected peak traffic
+- Canary deployment: 1% → 10% → 50% → 100%
+
+### Rollback Plan
+- Feature flag: Instant rollback to old code
+- Database: Backward-compatible migrations
+- Monitoring: Alert on error rate > 0.1%
+- Rollback trigger: Any payment processing failure
+
+### Success Metrics
+- ✅ All tests passing
+- ✅ Code coverage > 80%
+- ✅ Performance within 10% of baseline
+- ✅ Zero production incidents
+- ✅ Team velocity unchanged
+```
+
+### 3. Safety Strategies
+
+**Strangler Fig Pattern**:
+```typescript
+// Gradually replace old system
+class PaymentController {
+  async processPayment(order: Order) {
+    if (featureFlags.newPaymentFlow) {
+      return newPaymentService.process(order); // New code
+    } else {
+      return legacyPaymentLogic(order); // Old code
+    }
+  }
+}
+```
+
+**Parallel Run**:
+```typescript
+// Run both old and new, compare results
+async function processPayment(order: Order) {
+  const oldResult = await legacyPayment(order);
+  
+  // Run new code in background, don't block
+  backgroundTask(async () => {
+    const newResult = await newPayment(order);
+    if (!isEqual(oldResult, newResult)) {
+      logger.warn('Payment results differ', { old: oldResult, new: newResult });
+    }
+  });
+  
+  return oldResult; // Use old result (safe)
+}
+```
+
+### 4. Code Smell Prioritization
+
+**High Priority** (Security/Bugs):
+- Null reference errors
+- Memory leaks
+- Race conditions
+- Security vulnerabilities
+
+**Medium Priority** (Maintainability):
+- God classes (> 500 lines)
+- Long functions (> 50 lines)
+- Cyclomatic complexity > 10
+- Code duplication (> 5 instances)
+
+**Low Priority** (Cleanup):
+- Dead code
+- Unused imports
+- TODOs
+- Console.log statements
+
+### 5. Workflow
+
+1. **Identify Target**: What needs refactoring?
+2. **Assess Risk**: Impact analysis
+3. **Create Plan**: Step-by-step breakdown
+4. **Get Buy-in**: Team review
+5. **Prepare**: Tests, baselines, migrations
+6. **Execute**: Incremental changes
+7. **Monitor**: Metrics, alerts
+8. **Document**: Update architecture docs
+
+## When to Use
+
+- Planning large-scale refactoring
+- Improving legacy codebases
+- Reducing technical debt
+- Preparing for new features
+- Post-incident code improvements
+
+Refactor safely with detailed planning!