# CODE-ANALYSIS Pattern Analysis: Modular Script Architecture

**Status:** 📊 Architecture Redesign Complete  
**Focus:** Refactor review-code and optimize-command to use modular audit scripts  
**Tier Coverage:** FREE (3), STARTER (1)  
**Total Tokens:** ~9K (core commands) + new audit scripts

---

## Executive Summary

### Strategic Redesign: From Monolithic to Modular

Current CODE-ANALYSIS commands are too broad:
- `review-code` bundles style, security, performance, complexity, and architecture in one command
- `optimize-command` combines token, performance, and complexity analysis

**Proposed Solution:** Extract modular audit scripts that are called from parent commands.

### New Architecture

```
Parent Commands (orchestrators):
  ├─ /review-code (FREE) → calls 5 audit scripts
  ├─ /optimize-command (FREE) → calls 3 analysis scripts
  ├─ /minimize-tokens (STARTER) → existing
  ├─ /audit-security (NEW STARTER) → security-specific analysis
  ├─ /audit-performance (NEW STARTER) → performance-specific analysis
  └─ /audit-complexity (NEW STARTER) → complexity-specific analysis

Distributed Scripts in scripts/utils/roadcrew/:
  ├─ audit-style.ts → style, naming, documentation
  ├─ audit-security.ts → security vulnerabilities
  ├─ audit-performance.ts → speed, memory, optimization
  ├─ audit-complexity.ts → cyclomatic complexity, function size
  ├─ audit-architecture.ts → separation of concerns, DRY, patterns
  └─ code-analyzer.ts → shared utilities for all audits
```

---

## Current CODE-ANALYSIS Commands (To Be Refactored)

### 1. review-code (1,995 tokens) - FREE → REFACTORED

**Current Approach (Monolithic):**
Single command that checks:
- Style & naming
- Documentation & JSDoc
- Security issues (hardcoded values, auth)
- Architecture (SoC, DRY, function size)
- Performance (quota usage, API batching)
- Type safety & validation

**New Approach (Modular):**
Orchestrator that calls 5 audit scripts:
```bash
/review-code <issue_number>
  ├─ audit-style.ts (naming, formatting, docs)
  ├─ audit-security.ts (auth, data safety, injections)
  ├─ audit-performance.ts (quota, batching, optimization)
  ├─ audit-complexity.ts (function size, nesting)
  └─ audit-architecture.ts (SoC, DRY, patterns)
```

**Benefits:**
- Each audit script ~150-300 tokens (modular)
- Reusable scripts for other commands
- Easier to extend with new audit types
- Better token efficiency

---

### 2. minimize-tokens (3,946 tokens) - STARTER → UNCHANGED

**Purpose:** Command-level token optimization

**Capabilities:**
- Analyzes command token usage
- Detects redundancy and duplication
- Suggests script extraction
- Prioritizes by savings potential

**Note:** Keep as-is. Different purpose than code audits.

---

### 3. optimize-command (3,237 tokens) - FREE → REFACTORED

**Current Approach (Monolithic):**
Single command that analyzes:
- Complexity assessment
- Performance bottlenecks
- Token usage
- Optimization opportunities

**New Approach (Modular):**
Orchestrator that calls 3 analysis scripts:
```bash
/optimize-command <command_name>
  ├─ analyze-command-tokens.ts (token usage, redundancy)
  ├─ analyze-command-performance.ts (bottlenecks, speed)
  └─ analyze-command-complexity.ts (cyclomatic, nesting)
```

**Benefits:**
- Each script ~200-300 tokens
- Reusable for audit commands
- Faster, more focused analysis
- Easier to iterate on

---

## New Scripts to Create

### audit-style.ts (150-250 tokens)

**Purpose:** Analyze code style, naming, documentation

**Checks:**
- camelCase vs UPPER_SNAKE_CASE
- Verb prefixes on functions
- Boolean prefixes (is*, has*)
- JSDoc completeness
- Comment quality
- Line length & indentation

**Used by:**
- `/review-code`

---

### audit-security.ts (200-300 tokens)

**Purpose:** Security vulnerability analysis

**Checks:**
- Hardcoded credentials/API keys
- SQL injection vulnerabilities
- XSS vulnerabilities (DOM manipulation)
- Authentication/authorization issues
- Data safety (null checks, type validation)
- Unsafe external dependencies

**Used by:**
- `/review-code`
- `/audit-security` (new standalone command)

---

### audit-performance.ts (200-300 tokens)

**Purpose:** Performance profiling and optimization

**Checks:**
- API quota usage estimation
- Batching opportunities
- N+1 query patterns
- Memory leaks (uncleared timers, etc.)
- Slow function detection
- Inefficient loops/iterations

**Used by:**
- `/review-code`
- `/optimize-command`
- `/audit-performance` (new standalone command)

---

### audit-complexity.ts (150-250 tokens)

**Purpose:** Code complexity analysis

**Checks:**
- Cyclomatic complexity per function
- Function size (lines of code)
- Nesting depth
- Parameter count
- Branch count
- Cognitive complexity

**Used by:**
- `/review-code`
- `/optimize-command`
- `/audit-complexity` (new standalone command)

---

### audit-architecture.ts (200-300 tokens)

**Purpose:** Architectural pattern analysis

**Checks:**
- Separation of concerns
- DRY principle violations
- Single responsibility principle
- Composition over inheritance
- Design pattern usage
- Architectural inconsistencies

**Used by:**
- `/review-code`

---

### code-analyzer.ts (300-400 tokens)

**Purpose:** Shared utilities for all audit scripts

**Provides:**
- File discovery and reading
- AST parsing (for JS/TS)
- Complexity calculation utilities
- Report generation helpers
- Finding formatting & prioritization

**Used by:**
- All audit scripts above

---

## Total Opportunity Impact

| Phase | Scripts Created | Tokens | Savings | Commands Affected |
|-------|-----------------|--------|---------|-------------------|
| **Phase 1** | code-analyzer.ts | 300-400 | - | Foundation |
| **Phase 2a** | audit-style.ts | 150-250 | 200-300 tokens | review-code |
| **Phase 2b** | audit-security.ts | 200-300 | 200-300 tokens | review-code, audit-security |
| **Phase 2c** | audit-performance.ts | 200-300 | 300-400 tokens | review-code, optimize-command, audit-performance |
| **Phase 2d** | audit-complexity.ts | 150-250 | 250-350 tokens | review-code, optimize-command, audit-complexity |
| **Phase 2e** | audit-architecture.ts | 200-300 | 200-300 tokens | review-code, audit-architecture |
| **Phase 3** | Refactor review-code | - | 800-1.2K tokens | review-code orchestrator |
| **Phase 4** | Refactor optimize-command | - | 600-800 tokens | optimize-command orchestrator |
| **Total** | **7 new scripts** | **~1.5-2K** | **2.45-3.45K tokens** | **Multiple commands** |

**Percentage Reduction:**
- review-code: 40-50% reduction (from monolithic to orchestrator)
- optimize-command: 25-30% reduction (modular approach)
- Overall CODE-ANALYSIS: 25-35% reduction

---

## Command Tier Analysis

### Current STATE

| Tier | Commands | Tokens |
|------|----------|--------|
| FREE | review-code, optimize-command | ~5K |
| STARTER | minimize-tokens | ~4K |
| **Total** | **3** | **~9K** |

### After NEW COMMANDS Added

| Tier | Commands | Tokens |
|------|----------|--------|
| FREE | review-code (refactored), optimize-command (refactored) | ~3K |
| STARTER | minimize-tokens, audit-security, audit-performance, audit-complexity | ~12K |
| **Total** | **6** | **~15K** |

### Tier Hierarchy
✅ SUBSET/SUPERSET maintained
- FREE: General code review orchestrator + command optimization
- STARTER: Deep analysis (security, performance, complexity) + token optimization

---

## Implementation Phases

### Phase 1: Foundation (1-2 days)
- [ ] Create code-analyzer.ts (shared utilities)

### Phase 2: Audit Scripts (5-7 days)
- [ ] Create audit-style.ts
- [ ] Create audit-security.ts
- [ ] Create audit-performance.ts
- [ ] Create audit-complexity.ts
- [ ] Create audit-architecture.ts

### Phase 3: Refactor review-code (2-3 days)
- [ ] Refactor to call all 5 audit scripts
- [ ] Consolidate reports
- [ ] Test orchestration

### Phase 4: Refactor optimize-command (2-3 days)
- [ ] Refactor to call 3 analysis scripts
- [ ] Reuse code-analyzer.ts
- [ ] Test orchestration

### Phase 5: New Standalone Commands (2-3 days)
- [ ] Create /audit-security command (calls audit-security.ts)
- [ ] Create /audit-performance command (calls audit-performance.ts)
- [ ] Create /audit-complexity command (calls audit-complexity.ts)

---

## Next Steps

1. Decide on phase breakdown
2. Walk through decision points (implementation order, script locations)
3. Create GitHub Epic with child issues
4. Begin Phase 1 implementation

See COMMAND-USE-CASE-PATTERNS.md for full pattern context.