# Issue #338 Refactoring Plan: IMPLEMENT Commands to Use Extracted Utilities

**Epic**: #360 | **Issue**: #338 | **Status**: IMPLEMENTATION GUIDE | **Created**: 2025-10-29

## Overview

This document provides a detailed implementation guide for refactoring 4 IMPLEMENT pattern cursor commands to use 3 extracted utility modules (orchestrators), reducing code duplication and token usage by 1.95-2.75K tokens.

---

## Extracted Utilities Reference

### 1. epic-orchestrator.ts
**Location**: `scripts/utils/roadcrew/epic-orchestrator.ts`  
**Purpose**: Centralized epic analysis and orchestration  
**Token Savings**: 600-900 tokens across commands  

**Key Functions**:
- `analyzeEpic(epicNumber, token)` - Full orchestration (replace ~400 lines)
- `fetchEpic()` - GitHub API wrapper
- `validateEpicTemplate()` - Template validation
- `checkCriticalQuestions()` - Parse/validate open questions
- `fetchChildIssues()` - Paginated child issue fetching
- `parseIssueDependencies()` - Dependency extraction
- `detectCircularDependencies()` - Circular dependency detection
- `assessRisk()` - Individual risk assessment
- `flagBreakingChanges()` - Breaking change detection
- `generateRiskReport()` - Formatted output

**Usage Pattern**:
```typescript
import { analyzeEpic } from './utils/roadcrew/epic-orchestrator';

const analysis = await analyzeEpic(360, token);
// Returns: { epic, childIssues, dependencies, risks, breaking_changes }
```

### 2. implementation-coordinator.ts
**Location**: `scripts/utils/roadcrew/implementation-coordinator.ts`  
**Purpose**: Implementation workflow orchestration  
**Token Savings**: 900-1.2K tokens across commands  

**Key Functions**:
- `runPreflightChecks(token)` - Auth/tools validation
- `detectProjectContext(techStackContent)` - Project type detection
- `createTODOList()` - Checkpoint list generation
- `createEpicBranch()` - Git branch creation
- `initializeMetrics()` / `updateMetrics()` / `aggregateMetrics()` - Metrics tracking
- `generateImplementationSummary()` - Summary formatting
- `addPendingClosureLabels()` - GitHub label management
- `createCheckpointCommitMessage()` - Commit message formatting
- `formatMetricsForPR()` - PR description formatting
- `waitForCI()` - CI status polling

**Usage Pattern**:
```typescript
import { 
  runPreflightChecks, 
  detectProjectContext,
  createTODOList,
  implementIssuesInOrder
} from './utils/roadcrew/implementation-coordinator';

await runPreflightChecks(token);
const context = await detectProjectContext(techStackContent);
const todos = createTODOList(epicNumber, 5);
```

### 3. testing-harness.ts
**Location**: `scripts/utils/roadcrew/testing-harness.ts`  
**Purpose**: Test framework and automation  
**Token Savings**: 450-650 tokens across commands  

**Key Functions**:
- `detectTestFramework()` - Framework detection
- `initializeTestFramework()` - Framework setup
- `generateTestCases()` - Test case generation
- `createTestFileContent()` - Test file generation
- `generateManualTestPlan()` - Manual test steps
- `parseFailures()` - CI failure parsing
- `generateFixSuggestions()` - Failure suggestions
- `generateCIStatusSummary()` - CI status summary

**Usage Pattern**:
```typescript
import { 
  detectTestFramework,
  generateTestCases,
  createTestFileContent
} from './utils/roadcrew/testing-harness';

const framework = await detectTestFramework(packageJson);
const testCases = await generateTestCases(criteria, title);
const testContent = createTestFileContent(framework, testCases, moduleName);
```

---

## Refactoring by Command

### 1. analyze-epic.md (PRIORITY: HIGH)

**Current Implementation**:
- Lines: ~450-500
- Contains: Epic fetching, validation, parsing, dependency analysis, risk assessment
- **Problem**: All logic inline, repeated in other commands

**Refactoring Strategy**:
Replace inline logic with orchestrator calls:

```
BEFORE:
┌─ Fetch Epic API
├─ Validate Template  
├─ Check Open Questions
├─ Fetch Child Issues (paginated)
├─ Parse Dependencies
├─ Assess Risks
├─ Generate Risk Report
└─ Display Output (KEEP THIS)

AFTER:
┌─ Import epic-orchestrator
├─ Call analyzeEpic() [replaces all above]
└─ Display Output (KEEP THIS)
```

**Changes Required**:
```markdown
## BEFORE:
```bash
# Epic API fetching (30 lines)
curl https://api.github.com/repos/org/repo/issues/360

# Template validation (20 lines)
# Custom validation logic

# Questions checking (25 lines)
# Parse questions section

# Child issue fetching (40 lines)
# Paginated loop with error handling

# Dependency parsing (35 lines)
# Complex parsing logic

# Risk assessment (50 lines)
# Risk scoring per issue
```

## AFTER:
```typescript
import { analyzeEpic } from './utils/roadcrew/epic-orchestrator';

const analysis = await analyzeEpic(360, process.env.GITHUB_TOKEN);
// Returns fully analyzed data in one call
```

**Token Savings**: 200-300 tokens (31 lines → 3 lines)  
**Estimated Effort**: 1-2 hours  
**Lines Modified**: ~200 (reduce ~150 lines)  
**Breaking Changes**: None (same output)  
**Test Coverage**: 80%+ (reuses orchestrator tests)

---

### 2. implement-epic.md (PRIORITY: MEDIUM)

**Current Implementation**:
- Lines: ~350-400
- Contains: Pre-flight, branch creation, issue orchestration, metrics, PR management
- **Problem**: Orchestration logic scattered, metrics tracking repeated

**Refactoring Strategy**:
Replace multiple sections with coordinator calls:

```
BEFORE:
├─ Pre-flight Checks (50 lines)
├─ Project Detection (30 lines)
├─ Branch Creation (20 lines)
├─ TODO List (40 lines)
├─ Metrics Initialization (30 lines)
├─ Issue Loop (80 lines)
├─ Metrics Aggregation (20 lines)
├─ PR Formatting (40 lines)
└─ Display (KEEP THIS)

AFTER:
├─ runPreflightChecks() (1 line)
├─ detectProjectContext() (1 line)
├─ createEpicBranch() (1 line)
├─ createTODOList() (1 line)
├─ Implementation Loop using coordinator (20 lines)
├─ aggregateMetrics() (1 line)
├─ formatMetricsForPR() (1 line)
└─ Display (KEEP THIS)
```

**Token Savings**: 300-500 tokens (250 lines → 100 lines)  
**Estimated Effort**: 2-3 hours  
**Lines Modified**: ~150 (reduce ~100 lines)  
**Breaking Changes**: None  
**Test Coverage**: 85%+

---

### 3. autopilot.md (PRIORITY: HIGHEST - Most Complex)

**Current Implementation**:
- Lines: ~600-700
- Contains: Full epic analysis + implementation + testing coordination
- **Problem**: All 3 orchestrators' functionality inlined, ~1200+ lines total

**Refactoring Strategy**:
- Phase 1 (Analysis): Use epic-orchestrator (600+ lines → 20 lines)
- Phase 2 (Implementation): Use implementation-coordinator (400+ lines → 50 lines)
- Testing: Use testing-harness (200+ lines → 30 lines)

```
BEFORE:
┌─ PHASE 1: Analysis
│  ├─ Fetch Epic (30 lines)
│  ├─ Validate (20 lines)
│  ├─ Check Questions (25 lines)
│  ├─ Fetch Issues (40 lines)
│  ├─ Parse Dependencies (50 lines)
│  └─ Risk Assessment (60 lines)
│
├─ PHASE 2: Implementation
│  ├─ Pre-flight (50 lines)
│  ├─ Detect Project (30 lines)
│  ├─ Create Branch (20 lines)
│  ├─ TODO List (40 lines)
│  ├─ Issue Loop (100+ lines)
│  ├─ Metrics (50 lines)
│  └─ PR Management (60 lines)
│
└─ Testing
   ├─ Detect Framework (20 lines)
   ├─ Generate Tests (40 lines)
   └─ CI Polling (30 lines)

AFTER:
┌─ PHASE 1: Analysis
│  └─ analyzeEpic() (1 line)
│
├─ PHASE 2: Implementation
│  ├─ runPreflightChecks() (1 line)
│  ├─ detectProjectContext() (1 line)
│  ├─ createEpicBranch() (1 line)
│  ├─ Issue Loop using coordinator (15 lines)
│  └─ formatMetricsForPR() (1 line)
│
└─ Testing
   └─ detectTestFramework() + generateTestCases() (5 lines)
```

**Token Savings**: 600-900 tokens (500 lines → 50 lines)  
**Estimated Effort**: 3-4 hours  
**Lines Modified**: ~450 (reduce ~350 lines)  
**Breaking Changes**: None  
**Test Coverage**: 90%+

---

## Implementation Sequence & Dependencies

**Dependency Graph**:
```
Epic-Orchestrator (standalone - no deps)
       ↓
analyze-epic ✓ (independent, can start first)
       ↓
Implement-Coordinator (depends on Epic-Orchestrator analysis results)
       ↓
implement-epic ✓ (depends on analyze-epic results)
       ↓
Testing-Harness (standalone - no deps)
       ↓
implement-issue (can run parallel with implement-epic)
       ↓
autopilot (depends on all 3 above)
```

**Recommended Implementation Order**:

1. **Week 1, Day 1**: analyze-epic.md (1-2 hours)
   - ✓ Independent - no dependencies
   - ✓ Simple replacement pattern
   - ✓ Highest token savings ratio (200-300 tokens / 1-2 hours)

2. **Week 1, Day 2**: implement-issue.md (1-2 hours)
   - ✓ Depends only on testing-harness (which is isolated)
   - ✓ Simplest refactoring (80-100 lines)

3. **Week 1, Day 3**: implement-epic.md (2-3 hours)
   - ✓ Depends on orchestrators being available
   - ✓ Moderate complexity (150 lines changed)

4. **Week 1, Day 4-5**: autopilot.md (3-4 hours)
   - ✓ Depends on all 3 orchestrators working correctly
   - ✓ Highest token savings (600-900 tokens)
   - ✓ Most complex (350+ lines changed)

---

## Implementation Checklist

### Phase 1: Prepare orchestrators
- [x] epic-orchestrator.ts exists and tested (Epic #128)
- [x] implementation-coordinator.ts exists and tested (Epic #128)
- [x] testing-harness.ts exists and tested (Epic #128)
- [ ] Integration tests created for combined usage

### Phase 2: Refactor analyze-epic.md
- [ ] Document current line-by-line breakdown
- [ ] Replace epic fetching with `analyzeEpic()` call
- [ ] Remove risk assessment code (use `generateRiskReport()`)
- [ ] Test end-to-end with Epic #360
- [ ] Verify output matches original
- [ ] Measure token savings
- [ ] Commit: "refactor(analyze-epic): Use epic-orchestrator"

### Phase 3: Refactor implement-issue.md
- [ ] Document current implementation
- [ ] Replace test framework detection with orchestrator
- [ ] Replace metrics tracking with coordinator
- [ ] Test with single issue
- [ ] Commit: "refactor(implement-issue): Use testing-harness and coordinator"

### Phase 4: Refactor implement-epic.md
- [ ] Document current implementation
- [ ] Replace preflight checks with orchestrator
- [ ] Replace project detection with orchestrator
- [ ] Replace metrics with coordinator
- [ ] Test with Epic #360
- [ ] Commit: "refactor(implement-epic): Use orchestrators"

### Phase 5: Refactor autopilot.md
- [ ] Document current implementation (largest)
- [ ] Replace Phase 1 analysis with epic-orchestrator
- [ ] Replace Phase 2 with implementation-coordinator
- [ ] Replace testing with testing-harness
- [ ] Run comprehensive end-to-end test
- [ ] Verify all 3 utility modules work together
- [ ] Commit: "refactor(autopilot): Use all 3 orchestrators"

### Phase 6: Validation
- [ ] All 4 commands pass functional tests
- [ ] Output format unchanged (user experience)
- [ ] Token reduction measured and documented
- [ ] No circular dependencies introduced
- [ ] Integration tests pass (orchestrators working together)

---

## Token Savings Breakdown

**Command-by-Command**:

| Command | Current | After | Savings | % Reduction |
|---------|---------|-------|---------|------------|
| analyze-epic | ~150 | ~50 | 100 | 67% |
| implement-issue | ~100 | ~60 | 40 | 40% |
| implement-epic | ~200 | ~100 | 100 | 50% |
| autopilot | ~500 | ~150 | 350 | 70% |
| **TOTAL** | ~950 | ~360 | ~590 | **62%** |

**Token Equivalent**:
- Code lines reduced: ~590 lines
- Estimated tokens saved: 1.95K-2.75K tokens (3.3 tokens/line average)
- Execution time: Improved (fewer lines to parse)
- Maintenance: Improved (single source of truth)

---

## Testing Strategy

### Unit Tests (Already Exist)
- epic-orchestrator: 28 tests ✅
- implementation-coordinator: 35 tests ✅
- testing-harness: 40 tests ✅

### Integration Tests (Need to Add)

**Test 1: analyze-epic with orchestrator**
```bash
npx ts-node scripts/test-analyze-epic-orchestrator.ts 360
# Expected: Full analysis output with <50 lines of markdown
```

**Test 2: implement-epic with coordinators**
```bash
npx ts-node scripts/test-implement-epic-coordinators.ts 360
# Expected: Full implementation orchestration with metrics
```

**Test 3: autopilot with all 3**
```bash
npx ts-node scripts/test-autopilot-orchestrators.ts 360
# Expected: Combined analysis + implementation + testing
```

### Behavioral Parity Tests
- Output format unchanged (users don't see difference)
- All functionality preserved (same behavior)
- Error handling improved (more specific messages)

---

## Success Criteria

✅ **Code Quality**:
- All 4 commands refactored to use orchestrators
- Code duplication eliminated (450+ lines removed)
- Maintainability improved (single source of truth)

✅ **Token Savings**:
- Baseline measured before refactoring
- After refactoring: 590 fewer lines (1.95-2.75K tokens)
- Execution time not degraded
- Memory footprint same/better

✅ **Testing**:
- All existing tests pass (80%+ coverage minimum)
- Integration tests added (command combinations)
- No functional regressions detected
- User experience unchanged

✅ **Documentation**:
- Commands updated with new patterns
- Orchestrators documented with examples
- Decision trees clarified
- Migration guide created

---

## Risk Analysis

**Low Risk**:
- Orchestrators already tested and stable (Epic #128 complete)
- Command output format unchanged (users won't notice)
- Fallback available (revert to inline if issues)

**Medium Risk**:
- Orchestrators may have edge cases with complex epics
- Mitigation: Comprehensive integration tests
- Mitigation: Test with multiple epic types

**Monitoring**:
- Token usage tracking (CI metrics)
- Error rate monitoring post-deployment
- User feedback collection

---

## Related Issues & Epics

- **Epic #128**: Extracted utilities (COMPLETE ✅)
- **Epic #360**: Scripts folder organization (THIS EPIC)
- **Issue #336**: Audit scripts (COMPLETE ✅)
- **Issue #337**: Document organization (COMPLETE ✅)
- **Issue #338**: Refactor commands (THIS ISSUE)
- **Issue #339**: Consolidate duplicates (NEXT)
- **Issue #340**: Archive obsolete (NEXT)

---

## Approval & Next Steps

**Ready for**:
1. Code review (refactoring approach)
2. Integration testing (orchestrator combinations)
3. Token measurement baseline (current state)
4. Implementation (4-5 day sprint)

**Metrics to Track**:
- Lines of code per command
- Token count per command execution
- Test coverage improvement
- Maintenance effort reduction

**Success Measurement**:
- 590+ lines of code removed ✓
- 1.95-2.75K tokens saved ✓
- 80%+ test coverage ✓
- Zero functional regressions ✓

---

**Document**: Epic #360 Issue #338 Implementation Guide  
**Author**: AI Pair Programmer  
**Status**: Ready for Implementation  
**Priority**: HIGH (high token savings, moderate effort)