# ANALYSIS Pattern: Commands & Scripts Analysis v1.6.x

**Goal:** Analyze ANALYSIS pattern commands to identify opportunities for reducing command duplication, reusing scripts, and extracting shared utilities.

**ANALYSIS Commands:** analyze-repo, analyze-multiplatform, classify-feedback, create-spec, create-prd, create-brd

---

## EXECUTIVE SUMMARY

### Decision Points

#### Phase Decisions

1. **Phase 1: Extract doc-generator.ts?**
   - **Status:** ✅ **APPROVED**
   - **Scope:** Consolidate create-spec, create-prd, create-brd template logic
   - **Expected Savings:** 3-5K tokens (30-40% reduction)
   - **Command Language Reduction:** 675-1,050 lines removed (~225-350 lines per command) - shift from imperative template code to declarative "generate X" calls
   - **Effort:** Low | **Timeline:** 1-2 days

2. **Phase 2: Extract repo-analyzer.ts?**
   - **Status:** ✅ **APPROVED**
   - **Scope:** Consolidate analyze-repo and analyze-multiplatform file scanning logic
   - **Expected Savings:** 2-3K tokens (20-25% reduction)
   - **Command Language Reduction:** 600-700 lines removed (~300-350 lines per command) - shift from "how to scan" to "what patterns to detect"
   - **Effort:** Medium | **Timeline:** 2-3 days
   - **Implementation Notes:**
     - Create a new `scripts/utils/analysis/repo-analyzer.ts` script that encapsulates file scanning, report generation, and path resolution.
     - This script will be used by both `analyze-repo` and `analyze-multiplatform`.
     - The `analyze-repo` command will call `repo-analyzer.ts` with a specific `type` (e.g., `standard`, `generated`, `generator`).
     - The `analyze-multiplatform` command will call `repo-analyzer.ts` with a `type` of `multiplatform`.
     - The `repo-analyzer.ts` script will then determine the appropriate file scanning logic based on the `type` and generate a report.

3. **Phase 3 Follow-up: Future feedback-classifier.ts Extensions?**
   - **Status:** ✅ **APPROVED**
   - **Scope:** Extend feedback-classifier.ts to support additional feedback types or replace triage-pr if command is re-introduced
   - **Impact:** Maintains consistency; low overhead since feedback-classifier.ts already exists
   - **Command Language Reduction:** 175-200 lines removed from classify-feedback - shift from algorithm implementation to rule configuration (already completed)
   - **Question:** Build extension capability into feedback-classifier.ts now, or defer until needed?

#### Support Decisions
4. **Script Organization & Imports**
   - **Status:** ✅ **APPROVED - USE `scripts/utils/roadcrew/`**
   - **Location:** Place all three new scripts in `scripts/utils/roadcrew/` (already established pattern for roadcrew utilities)
   - **Implementation Details:**
     - `repo-analyzer.ts` - NEW coordinator script (orchestrates detectDeployment, detectSchema, detectCICD)
     - `feedback-classifier.ts` - NEW feedback classification engine
     - `doc-generator.ts` - NEW document generation coordinator
     - Existing `detect-*` scripts remain unchanged (no breaking changes)
   - **Distribution:** All three scripts compile to `dist/scripts/utils/roadcrew/` and publish to customers
   - **Rationale:** Uses existing pattern, avoids renaming published scripts, maintains consistency

5. **Testing Strategy**
   - **Status:** ✅ **APPROVED - BOTH UNIT + INTEGRATION TESTS**
   - **Unit Tests** (`scripts/__tests__/`):
     - `doc-generator.test.ts` - Test template registry, markdown rendering, formatting utilities
     - `repo-analyzer.test.ts` - Test file scanning orchestration, report generation, path resolution
     - `feedback-classifier.test.ts` - Test text analysis, classification rules, label management
   - **Integration Tests** (`scripts/__tests__/`):
     - `analyze-repo.integration.test.ts` - Verify output identical before/after refactoring
     - `classify-feedback.integration.test.ts` - Verify output identical before/after refactoring
     - `create-spec.integration.test.ts` - Verify output identical before/after refactoring
     - `create-prd.integration.test.ts` - Verify output identical before/after refactoring
     - `create-brd.integration.test.ts` - Verify output identical before/after refactoring
   - **Test Coverage:** Unit tests verify script correctness; integration tests verify commands still work identically
   - **Rationale:** Critical commands require both internal correctness and integration validation; catches both bugs and breaking changes

6. **Measurement & Validation**
   - **Status:** ✅ **APPROVED - BOTH + PERFORMANCE BENCHMARKS**
   - **Phase 1: Manual Baseline (Before refactoring starts)**
     - One-time manual token count of all ANALYSIS commands (establish credibility)
     - Performance benchmark: execution time, API call volume, file sizes
     - Documented in `config/token-baseline.json` and `config/performance-baseline.json`
   - **Phase 2: Automated CI/CD Tracking (During refactoring)**
     - New utility: `scripts/utils/token-counter.ts` (counts tokens in command files)
     - CI/CD job: `npm run measure-tokens` runs on every commit
     - Tracks delta vs. baseline after each phase
     - Stores history in `config/token-history.json`
   - **Phase 3: Performance Re-Benchmark (After each phase)**
     - Measure actual execution time improvement
     - Measure actual LLM API call reduction (in practice)
     - Compare against estimates in ANALYSIS_SCRIPTS_BY_COMMAND.md
     - Validate Phase 1, 2, 3 savings independently
   - **Deliverables:**
     - `config/token-baseline.json` - Initial measurements
     - `config/token-history.json` - Phase-by-phase tracking
     - `config/performance-baseline.json` - Initial performance metrics
     - Post-refactoring report: Expected vs. Actual savings
   - **Rationale:** Credible baseline + automated tracking + performance validation demonstrates ROI and prevents regressions

7. **Rollout Order**
   - **Status:** ✅ **APPROVED - SEQUENTIAL (OPTION A)**
   - **Rationale:** No external customers yet, so simplicity/clarity preferred over incremental deployment strategy
   - **Implementation Timeline:**
     - **Phase 1 (Week 1, Days 1-2):** Extract doc-generator.ts
       - Extract, unit test, integrate into create-spec/prd/brd
       - Internal testing + performance benchmark
       - Measure Phase 1 token savings (3-5K tokens expected)
       - Deploy internally / publish to dist/
     - **Phase 2 (Week 1, Days 3-5):** Extract repo-analyzer.ts
       - Extract, unit test, integrate into analyze-repo/multiplatform
       - Internal testing + performance benchmark
       - Measure Phase 2 token savings (2-3K tokens expected)
       - Deploy internally / publish to dist/
     - **Phase 3 (Week 2, Days 1-2):** Phase 3 Follow-up (if needed)
       - Extend feedback-classifier if new commands require it
       - Deploy internally / publish to dist/
   - **Deployment Strategy:** Internal-only until all phases complete; then publish as unified distribution
   - **Success Criteria:** All phases complete, tested, and deployed within 2 weeks; achieve 5.7-8.8K token savings (22-34% reduction)

#### Completed Decisions

- ✅ **Remove triage-pr:** Low usage (1 optional parent reference), no breaking changes
- ✅ **Extract feedback-classifier.ts:** Immediate consolidation with classify-feedback, Phase 3 complete

### Current State
- **6 ANALYSIS commands** consuming **25,911 tokens** (40% of total freemium token budget)
- **Significant duplication** across 2 distinct patterns
- Opportunity to reduce tokens by **22-34%** (5.7-8.8K tokens)

### Key Findings

**Pattern 1: Documentation Generation (40-50% duplicate code)**
- Commands: `create-spec`, `create-prd`, `create-brd`
- Shared: Template system, markdown generation, output patterns, source (analyze-repo findings)
- **ROI:** High - straightforward consolidation, immediate impact

**Pattern 2: Repository Analysis (35-45% duplicate code)**
- Commands: `analyze-repo`, `analyze-multiplatform`
- Shared: File scanning, report generation, path validation, file I/O
- **ROI:** Medium - more complex separation of concerns required

### Recommendations (In Priority Order)

**Phase 1: Quick Win (Documentation Consolidation)**
1. Extract `doc-generator.ts` script with:
   - Template registry (Spec, PRD, BRD templates)
   - Shared markdown rendering logic
   - Common formatting utilities
2. Refactor create-spec, create-prd, create-brd to thin wrappers calling doc-generator
3. **Expected Savings:** 3-5K tokens (30-40% reduction on these 3 commands)
4. **Effort:** Low (clear pattern, high reuse)
5. **Timeline:** 1-2 days

**Command Language Reduction Opportunity:**
- Current: Each command has ~300-400 lines describing template logic, markdown formatting, file I/O
- After: Each command reduced to ~50-75 lines (parameter handling + doc-generator call)
- **Reduction:** ~225-350 lines per command × 3 = ~675-1050 lines removed from command text
- **Benefit:** Command language becomes declarative ("generate spec from these inputs") vs. imperative (detailed template/formatting instructions)
- **Implementation:** Move all procedural logic into doc-generator.ts; command text focuses on *what* to generate, not *how*

---

**Phase 2: Core Foundation (Analysis Extraction)**
1. Extract `repo-analyzer.ts` script with:
   - File system scanning utilities
   - Report templating engine
   - Path resolution logic
2. Refactor analyze-repo and analyze-multiplatform to use shared foundation
3. **Expected Savings:** 2-3K tokens (20-25% reduction on these 2 commands)
4. **Effort:** Medium (requires careful API design for type-specific extensions)
5. **Timeline:** 2-3 days

**Command Language Reduction Opportunity:**
- Current: analyze-repo has ~450+ lines describing file detection, report generation, path validation
- Current: analyze-multiplatform has ~400+ lines with similar file scanning + API-specific detection
- After: Both commands reduced to ~100-150 lines each (detection logic + repo-analyzer call)
- **Reduction:** ~300-350 lines per command × 2 = ~600-700 lines removed from command text
- **Benefit:** Command text shifts from "how to scan files and generate reports" to "what patterns to detect and how to classify findings"
- **Trade-off:** Requires designing extensible API in repo-analyzer.ts so commands can inject custom detectors
- **Implementation:** repo-analyzer.ts provides scanning/reporting infrastructure; commands provide detection logic

---

**Phase 3: Classification Engine (Completed)**
- ✅ Removed: `triage-pr` (only 1 parent command reference, optional workflow)
- ✅ Extracted: `feedback-classifier.ts` script with:
  - Text analysis utilities
  - Classification rules engine
  - Label/category management
- ✅ Refactored: `classify-feedback` to use shared classifier
- **Expected Savings:** 1.5K tokens (42% reduction on classify-feedback)
- **Effort:** Low (single command consolidation)
- **Timeline:** Completed

**Command Language Reduction Opportunity:**
- Current: classify-feedback has ~250+ lines describing text analysis, classification algorithm, label assignment
- After: classify-feedback reduced to ~50-75 lines (parameter handling + feedback-classifier.ts call)
- **Reduction:** ~175-200 lines removed from command text
- **Benefit:** Command text becomes "classify this feedback using these rules" vs. detailed algorithm implementation
- **Implementation:** feedback-classifier.ts encapsulates all NLP/pattern matching; command text focuses on rule configuration

### Total Impact

| Metric | Current | After Consolidation | Savings |
|--------|---------|-------------------|---------|
| Token Count | 25,911 | 17,111 - 20,211 | 5,700 - 8,800 |
| % of Budget | 40% | 26-31% | 9-14pp |
| # Commands | 6 | 6 (but with 2 new utility scripts) | 0 (refactored) |
| # Shared Scripts | 0 | 2 | +2 |
| Code Duplication | ~40-45% | <10% | 30-40pp |

### Implementation Roadmap

```
Week 1:
  ✅ Day 1: Extract feedback-classifier.ts → refactor classify-feedback (COMPLETED)
  Day 2: Extract doc-generator.ts → refactor create-spec/prd/brd
  
Week 2:
  Day 1: Extract repo-analyzer.ts → refactor analyze-repo/multiplatform
  Day 2: Integration testing and validation
  
Week 3:
  Day 1: Documentation updates
  Day 2: Performance benchmarking
```

---

## DETAILED ANALYSIS

## Command 1: analyze-repo

**Tier:** FREE | **Tokens:** 6,746 | **Calls:** 16 commands

### Command Text Summary

Scans project files to detect:
- Deployment method, schema, and CI/CD configuration
- Technology versions
- Creates timestamped analysis report in `config/reports/`
- Updates `memory-bank/techContext.md` with latest configuration

**Parameters:**
- `--repo` (optional): External repository path
- `--type` (optional): generator, generated, or standard (default)

**When to use:**
- Initial setup of roadcrew
- After major infrastructure changes
- Before starting new release
- When config files are out of sync
- Analyzing external repositories
- Comparing tech stacks across multiple organization repositories

### Scripts Called

**Core Scripts (compiled from dist/):**
- `dist/scripts/utils/detect-deployment.js` - Detects deployment method, platform, configuration
- `dist/scripts/utils/detect-schema.js` - Detects database ORM, schema, models
- `dist/scripts/utils/detect-cicd.js` - Detects CI/CD platform, workflows, test frameworks

**Helper Scripts:**
- `scripts/ensure-built.ts` - Ensures detection utilities are compiled before use
- `scripts/init-instance.sh` - Creates missing folders for generated app instances

**File Operations:**
- Reads: package.json, package-lock.json, yarn.lock, Dockerfile, docker-compose.yml, .github/workflows/*.yml
- Writes: config/reports/YYYY-MM-DD-HHMMSS.md, memory-bank/techContext.md, config/schema/schema.prisma

---

## Command 2: analyze-multiplatform

**Tier:** ENTERPRISE | **Tokens:** 4,596 | **Calls:** 23 commands

### Command Text Summary

Multi-repo architecture analysis for enterprise environments. Analyzes cross-repository dependencies, API patterns, and complexity. Detects Express and Next.js API patterns, mixed dependencies, and generates architecture report.

**Capabilities:**
- Detects Express API routes (`/api/`, `app.get()`, `app.post()`)
- Detects Next.js API routes (`/api/**/route.ts`)
- Detects Next.js pages API (`/pages/api/**/*.ts`)
- Detects mixed framework dependencies
- Identifies platform/framework conflicts
- Creates timestamped analysis report

**Output:** `config/multiplatform-analysis/YYYY-MM-DD-HHMMSS.md` (or `.json`)

### Scripts Called

**Core Scripts:**
- `dist/scripts/utils/analyze-multiplatform.ts` - Compiled multi-repo analysis utility
- Pattern detection for Express, Next.js APIs
- Multi-repo coordination analysis

**Shared with analyze-repo:**
- File scanning utilities
- Report generation logic
- Path validation

---

## Command 3: classify-feedback

**Tier:** FREE | **Tokens:** 3,227 | **Calls:** 5 commands

### Command Text Summary

Classifies and triages user feedback into categories. Analyzes feedback by:
- Type (feature request, bug, question, etc.)
- Priority (critical, high, medium, low)
- Relevance (epic-related, blocked by, duplicate, etc.)
- Sentiment (positive, neutral, negative)

**Input:** Feedback, GitHub issues, user comments
**Output:** Classified feedback with suggested epic assignment

### Scripts Called

**Classification Scripts:**
- `scripts/utils/feedback-classifier.ts` ✅ **[NEW SHARED SCRIPT]**
  - Text analysis utilities
  - Classification rules engine
  - Pattern matching for feedback categorization
  - Label/category management

---

## Command 4: create-spec

**Tier:** FREE | **Tokens:** 3,352 | **Calls:** 13 commands

### Command Text Summary

Generate technical specification from repository analysis. Creates detailed technical spec documents based on:
- analyze-repo findings (tech stack, deployment, CI/CD)
- Existing code structure
- Configuration files
- Dependencies and versions

**Output:** `docs/SPEC.md` - Technical specification document

### Scripts Called

**Document Generation:**
- Template system for spec creation
- Format converters (markdown, etc.)
- Code snippet extraction
- Version documentation

**Shared Logic:**
- analyze-repo findings
- Documentation templates (shared with create-prd, create-brd)
- Markdown generation

---

## Command 5: create-prd

**Tier:** FREE | **Tokens:** 4,038 | **Calls:** 12 commands

### Command Text Summary

Generate product requirements document from analysis. Creates PRD documents based on:
- Repository analysis findings
- Existing documentation
- Feature set from codebase
- Deployment characteristics

**Output:** `docs/PRD.md`
 - Product requirements document

### Scripts Called

**Document Generation:**
- Template system for PRD creation
- Feature extraction from code
- Documentation formatting
- Requirement synthesis

**Shared Logic:**
- Documentation templates (same as create-spec, create-brd)
- Template rendering engine
- Markdown generation

---

## Command 6: create-brd

**Tier:** FREE | **Tokens:** 4,052 | **Calls:** 11 commands

### Command Text Summary

Generate business requirements document from analysis. Creates BRD documents based on:
- Repository analysis findings
- Business model indicators
- Deployment strategy
- Technology choices

**Output:** `docs/BRD.md` - Business requirements document

### Scripts Called

**Document Generation:**
- Template system for BRD creation
- Business model analysis
- Documentation formatting
- Requirement synthesis

**Shared Logic:**
- Documentation templates (same as create-spec, create-prd)
- Template rendering engine
- Markdown generation

---

## Completed Phase 3: feedback-classifier.ts

### Script Created: `scripts/utils/feedback-classifier.ts`

**Purpose:** Unified classification engine for feedback analysis

**Architecture:**
```typescript
// Text analysis and pattern matching
export interface ClassificationResult {
  type: 'feature-request' | 'bug' | 'question' | 'improvement' | 'other';
  priority: 'critical' | 'high' | 'medium' | 'low';
  relevance: 'epic-related' | 'blocked-by' | 'duplicate' | 'unrelated';
  sentiment: 'positive' | 'neutral' | 'negative';
  confidence: number; // 0-1
  suggestedLabels: string[];
  suggestedEpic?: string;
}

export class Classifier {
  private rules: ClassificationRule[];
  private patterns: PatternMatcher;
  
  classify(text: string, context?: ClassificationContext): ClassificationResult;
  addRule(rule: ClassificationRule): void;
  getLabelsForType(type: string): string[];
}
```

**Shared Components:**
- Text normalization and parsing
- Pattern matching engine
- Classification rules registry
- Label management
- Confidence scoring

**Commands Using This Script:**
- ✅ `classify-feedback` - Text classification for user feedback
- Future: Could be extended if new feedback classification commands emerge

---

## Analysis Summary

### Total Commands (After Refactoring): 6
### Total Tokens: 25,911

### Token Breakdown
- **Documentation Generation (create-spec/prd/brd):** 11,442 tokens (44%)
- **Analysis (analyze-repo/multiplatform):** 11,342 tokens (44%)
- **Classification (classify-feedback):** 3,227 tokens (12%) - Now using shared feedback-classifier.ts

### Completed Optimizations

✅ **Phase 3: Triage-PR Removal & Feedback-classifier.ts Creation**
- Removed `triage-pr` (only 1 optional parent reference, low integration)
- Token savings: 1,052 tokens removed from consideration
- Extracted `feedback-classifier.ts` shared script
- Refactored `classify-feedback` to use new classifier
- Code duplication reduced from 50-60% to <10% for classify-feedback
- Design approach: Keep focused on classify-feedback, extend when needed (no speculative features)

### Remaining Opportunities

**Pattern 1: Documentation Generation (40-50% duplicate code)**
- **Estimated Savings:** 3-5K tokens (30-40% reduction)
- **Status:** Ready for Phase 1

**Pattern 2: Repository Analysis (35-45% duplicate code)**
- **Estimated Savings:** 2-3K tokens (20-25% reduction)
- **Status:** Ready for Phase 2

### Total Potential Remaining Savings

**Conservative estimate:** 5.7-8.8K tokens (22-34% reduction)
**Breaking down by script:**
- `doc-generator.ts`: 3-5K tokens saved
- `repo-analyzer.ts`: 2-3K tokens saved