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

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

**RELEASE Commands:** scope-release, enrich-release, validate-release, guide-release, create-release-pr

---

## EXECUTIVE SUMMARY

### Decision Points

#### Phase Decisions

1. **Phase 1: Extract release-issue-manager.ts?**
   - **Status:** ⏳ **PENDING DECISION**
   - **Scope:** Consolidate scope-release and enrich-release GitHub issue creation and management logic
   - **Expected Savings:** 2-4K tokens (reduction pending analysis)
   - **Command Language Reduction:** TBD (pending analysis)
   - **Effort:** Medium | **Timeline:** 2-3 days

2. **Phase 2: Extract release-validator.ts?**
   - **Status:** ⏳ **PENDING DECISION**
   - **Scope:** Consolidate validate-release and create-release-pr validation logic
   - **Expected Savings:** 1-2K tokens (reduction pending analysis)
   - **Command Language Reduction:** TBD (pending analysis)
   - **Effort:** Low-Medium | **Timeline:** 1-2 days

3. **Phase 3: Future Extensions?**
   - **Status:** ⏳ **PENDING DECISION**
   - **Scope:** Extend extracted utilities for multi-repo release coordination
   - **Impact:** Support Enterprise-tier release workflows
   - **Rationale:** TBD (pending early decisions)

#### Support Decisions

4. **Script Organization & Imports**
   - **Status:** ⏳ **PENDING DECISION**
   - **Question:** Where should release-related scripts live? (scripts/utils/roadcrew/)

5. **Testing Strategy**
   - **Status:** ⏳ **PENDING DECISION**
   - **Question:** Unit, integration, or both?

6. **Measurement & Validation**
   - **Status:** ⏳ **PENDING DECISION**
   - **Question:** How do we validate token savings?

7. **Rollout Order**
   - **Status:** ⏳ **PENDING DECISION**
   - **Question:** Sequential, parallel, or phased?

---

### Current State
- **5 RELEASE commands** consuming ~21K tokens
- **Duplication patterns** to be identified
- **Optimization opportunity:** TBD (pending detailed analysis)

### Key Findings

**Pattern Analysis Required:**
- Need to determine code duplication across commands
- Need to identify shared utilities and patterns
- Need to estimate token savings

---

## DETAILED ANALYSIS

## Command 1: scope-release

**Tier:** STARTER | **Tokens:** 10,554 | **Calls:** 10 commands

### Command Text Summary

Converts scoped release plan to GitHub epics and issues. Parses current-release.md, validates epic structure and spec references, creates Release tracking issue, processes one epic at a time, applies labels/assignees, writes GitHub issue numbers back to markdown.

**Critical Policy:** GitHub-First, No Interim Documentation - creates all issues directly in GitHub, never creates interim .md files.

**Capabilities:**
- Parse release file (current-release.md or minor-release.md)
- Validate epic structure and spec references
- Create Release tracking issue (single source of truth)
- Check for duplicate issues (closes old, creates new)
- Process epics one at a time with child issues
- Read linked spec files for each epic
- Research specific details for each issue
- Auto-fill metadata from tech-stack.md
- Apply labels, assignees, project assignments
- Write GitHub issue numbers back to markdown
- Verification checks (all issues created, no interim files)

**Key Files & I/O:**
- **Reads:** milestones/current-release.md or minor-release.md, context/specs/*.md, memory-bank/techContext.md
- **Writes:** GitHub issues (epic + child), milestones/current-release.md (with issue numbers), memory-bank/activeContext.md (legacy: context/vision.md) (synced)
- **Scripts:** validate-release, analyze-repo (cached)

### Scripts Called

**Direct Script Calls:**
- Runs TypeScript script: `scripts/scope-release.ts`
- Calls GitHub API directly via Octokit
- Calls validate-release for verification

**Helper Functions:**
- Release file parsing and validation
- Spec file reading and analysis
- Issue title/body generation from templates
- Duplicate detection
- Metadata auto-fill from tech-stack.md

---

## Command 2: enrich-release

**Tier:** STARTER | **Tokens:** 3,229 | **Calls:** 7 commands

### Command Text Summary

Research and populate detailed issue specifications in `current-release.md`. Fills in all `<!-- TODO: enrich -->` placeholders by reading spec files, analyzing codebase, researching requirements, generating comprehensive implementation details.

**Capabilities:**
- Parse current-release.md structure
- Load spec files linked to each epic
- Load tech context from memory-bank/techContext.md
- Research each issue's requirements
- Generate comprehensive detail sections:
  - Overview & User Story
  - Acceptance Criteria
  - Technical Implementation
  - Dependencies
  - Estimated Effort
- Support partial enrichment (from/to specific issues)
- Dry-run mode to preview changes
- Force overwrite of existing content

**Key Files & I/O:**
- **Reads:** milestones/current-release.md, context/specs/*.md, memory-bank/techContext.md
- **Writes:** milestones/current-release.md (populated sections)
- **Flags:** --from, --to, --dry-run, --force

### Scripts Called

**Direct Calls:**
- Runs TypeScript script: `scripts/enrich-release.ts`
- Calls analyze-repo (or reads cached tech-stack.md)

**Internal Logic:**
- Spec file parsing and section extraction
- Issue content generation from templates
- Tech context extraction and formatting
- Dependency validation
- Content validation before writing

---

## Command 3: validate-release

**Tier:** FREE | **Tokens:** 1,592 | **Calls:** 4 commands

### Command Text Summary

Pre-flight validation for release files before creating GitHub issues. Validates current-release.md or minor-release.md to ensure all issues are fully enriched, classification scores/zones correct, dependencies valid, file references accurate, acceptance criteria meet quality standards.

**Capabilities:**
- Validate classification (1-10 scale, zone matches)
- Check completeness (no TODO placeholders)
- Validate dependency references
- Validate file references
- Quality checks (criteria count, complexity match)
- Generate validation report with warnings/suggestions

**Validation Checks:**
- Classification validation (1-10 scale, zone matching)
- Completeness validation (no TODO placeholders)
- Dependency validation (circular dependency detection)
- File reference validation
- Quality validation (criteria count, complexity match)

**Key Files & I/O:**
- **Reads:** milestones/current-release.md or minor-release.md, memory-bank/techContext.md
- **Writes:** Validation report (console output)
- **Flags:** --current, --minor, --file

### Scripts Called

**Direct Calls:**
- Runs TypeScript script: `scripts/validate-release.ts`

**Internal Logic:**
- Release file parsing
- Classification validation
- Dependency graph analysis (circular detection)
- Content validation
- Report generation

---

## Command 4: guide-release

**Tier:** FREE | **Tokens:** 3,725 | **Calls:** 15 commands

### Command Text Summary

Walk through guided release transition process, ensuring all documentation aligned before running advance-release and scope-release. Creates TODO list with human and AI tasks in proper order (pre-flight checks → vision alignment → release documentation → approval).

**Capabilities:**
- Check current release completion
- Analyze recent code changes (last 30 days)
- Review tech stack state
- Align vision with proposed work
- Review and update planning documents
- Check release documentation alignment
- Validate all documents are ready
- Display next steps with proper sequencing

**Workflow Phases:**
1. Phase 1: Pre-Flight Checks (current release complete?, repo state)
2. Phase 2: Vision Alignment (future work reviewed, constraints understood)
3. Phase 3: Release Documentation (epics, specs, current-release aligned)
4. Phase 4: Approval & Readiness (all systems go)

**Key Files & I/O:**
- **Reads:** milestones/current-release.md, milestones/future-releases.md, memory-bank/activeContext.md (legacy: context/vision.md), memory-bank/techContext.md
- **Writes:** TODO list (console), guided workflow checklist
- **Cost Optimization:** 65-70% token savings vs verbose mode

### Scripts Called

**Direct Calls:**
- Runs TypeScript script: `scripts/guide-release.ts`
- Calls git log for recent changes
- Calls analyze-repo (or reads cached tech-stack.md)

**Internal Logic:**
- Git log parsing (recent commits)
- Tech stack analysis
- Document structure validation
- Checklist generation
- Consolidated AI tasks

---

## Command 5: create-release-pr

**Tier:** FREE | **Tokens:** 1,940 | **Calls:** 3 commands

### Command Text Summary

Create release PR from dev → main with automatic issue closure tracking. Detects all issues with `pending-closure` label, verifies merged PRs, builds closure keywords, creates PR body with issue summaries, detects diff stats.

**Capabilities:**
- Detect pending issues by label
- Verify merged PRs to dev
- Build closure keywords (Closes #N)
- Generate PR body with issue summaries
- Detect diff statistics
- Create PR from dev → main
- Auto-close issues when merged
- Support for both epic and child issues

**Key Files & I/O:**
- **Reads:** Git commit history, GitHub PR/issue data
- **Writes:** GitHub PR (from dev → main)
- **Flags:** --version, --title, --milestone

### Scripts Called

**Direct Calls:**
- Runs TypeScript script: `scripts/create-release-pr.ts`
- Calls GitHub API via gh CLI
- Git log and diff commands

**Internal Logic:**
- GitHub issue label filtering
- PR verification
- Closure keyword generation
- Diff statistics extraction
- PR body formatting

---

## Analysis Summary

### Total Commands: 5
### Total Tokens: ~21,041

### **Key Duplication Opportunities:**

1. **GitHub Issue Operations (scope-release + create-release-pr):**
   - Both query GitHub API
   - Both manage issue labels and metadata
   - Both handle issue/PR creation
   - **Extract Potential:** `release-issue-manager.ts` (GitHub operations coordinator)
   - **Token Savings:** 1.5-2K tokens

2. **Validation & Enrichment (enrich-release + validate-release):**
   - Both parse release files
   - Both validate issue structure
   - Both work with classification/zones
   - **Extract Potential:** `release-validator.ts` (validation + enrichment framework)
   - **Token Savings:** 800-1.2K tokens

3. **Spec & Tech Stack Reading (all 5 commands):**
   - All read spec files and tech-stack.md
   - All parse release markdown structure
   - All validate issue metadata
   - **Extract Potential:** `release-file-manager.ts` (file I/O coordinator)
   - **Token Savings:** 500-800 tokens

**Total Phase 1 + Phase 2 Potential Savings:** 2.8-4K tokens (13-19% of RELEASE total)

**Next Steps:**
1. Present 7 decisions for RELEASE pattern optimization
2. Create GitHub Epic with child issues
3. Proceed to PUBLISH pattern analysis