---
roadcrew_template_name: "enrich-release.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# Enrich Release

Research and populate detailed issue specifications in `current-release.md`.

## What This Command Does

Fills in all `<!-- TODO: enrich -->` placeholders in `current-release.md` by:
1. Reading the spec files linked in each epic
2. Analyzing the codebase using `analyze-repo` output
3. Researching each issue's requirements
4. Generating comprehensive details for implementation

## Prerequisites

- `memory-bank/releases/current-release.md` exists (generated by `/advance-release`)
- All epics have `**Related Spec**:` links
- `memory-bank/techContext.md` exists (run `/analyze-repo` if missing)
- Spec files referenced in epics exist

## Usage

```bash
# Enrich all issues from the beginning
/enrich-release

# Start enrichment from a specific issue
/enrich-release --from 2.3

# Re-enrich specific issues (overwrites existing content)
/enrich-release --from 1.1 --to 1.5

# Dry run to see what would be enriched
/enrich-release --dry-run
```

## Command Execution

This command runs the TypeScript script:
- **Instance installation:** `scripts/enrich-release.ts`
- **Submodule installation:** `.roadcrew/scripts/enrich-release.ts` or `roadcrew/scripts/enrich-release.ts`

**Flags:**
- `--from <issue#>` - Start from specific issue (e.g., 1.1, 2.3)
- `--to <issue#>` - End at specific issue (optional, for ranges)
- `--dry-run` - Show what would be enriched without making changes
- `--force` - Overwrite existing enriched content

## Process

### 1. Load Current Release

Read `memory-bank/releases/current-release.md` and parse structure:
- Extract all epics
- For each epic, extract all issues
- Identify issues with `<!-- TODO: enrich -->` markers
- Build enrichment queue

### 2. Load Context

**Load spec files:**
```typescript
for (const epic of epics) {
  const specPath = extractSpecPath(epic.relatedSpec);
  const specContent = await fs.readFile(specPath, 'utf-8');
  specCache[epic.title] = specContent;
}
```

**Load tech context:**
```typescript
const techStack = await fs.readFile('memory-bank/techContext.md', 'utf-8');
const repoContext = parseTechStack(techStack);
```

### 3. Enrich Each Issue

For each issue in the queue:

#### 3.1 Parse Issue Structure

```typescript
interface IssueToEnrich {
  epicNumber: number;
  issueNumber: number;
  title: string;
  classification: number;
  zone: string;
  specReference: string;
  sections: {
    overview: string | null; // null = needs enrichment
    acceptanceCriteria: string | null;
    technicalImplementation: string | null;
    dependencies: string | null;
  };
}
```

#### 3.2 Research Issue Details

**From spec file:**
1. Locate the spec section (using `specReference`)
2. Extract:
   - Issue description and context
   - Acceptance criteria (explicit or implicit)
   - Technical approach/implementation details
   - Files to modify
   - Dependencies on other issues

**From tech-stack.md:**
1. Identify relevant technologies
2. Find existing patterns/conventions
3. Locate related code files

**Example research process:**
```typescript
async function researchIssue(issue: IssueToEnrich, spec: string, techContext: TechContext) {
  // Find spec section
  const section = findSpecSection(spec, issue.specReference);
  
  // Extract overview and user story
  const overview = extractOverview(section);
  const userStory = generateUserStory(issue.title, overview, issue.classification);
  
  // Extract acceptance criteria
  const acceptanceCriteria = extractAcceptanceCriteria(section);
  
  // Generate technical implementation
  const techImplementation = await generateTechnicalApproach(
    section,
    techContext,
    issue.classification
  );
  
  // Identify dependencies
  const dependencies = extractDependencies(section, issue);
  
  return {
    overview: `${overview}\n\n**User Story**:\n${userStory}`,
    acceptanceCriteria,
    technicalImplementation: techImplementation,
    dependencies
  };
}
```

#### 3.3 Generate Content

**Overview & User Story:**
```markdown
**Overview & User Story**:
Replace emoji-based risk indicators (🟢 🟡 🔴) with a standardized 1-10 classification field in all issue templates. This provides more granular complexity assessment and enables TOC-based resource allocation.

**User Story**:
**As a** project manager  
**I want** issues to have 1-10 classification scores  
**So that** I can assign work based on complexity and protect expert capacity
```

**Acceptance Criteria:**
```markdown
**Acceptance Criteria**:
- [ ] All issue templates updated with classification field (1-10 scale)
- [ ] Classification field includes zone mapping (ai-solo, ai-led, ai-assisted, ai-limited)
- [ ] Old emoji indicators (🟢 🟡 🔴) removed from templates
- [ ] Template documentation updated with classification examples
- [ ] Validation passes for classification field (must be 1-10)
```

**Technical Implementation:**
```markdown
**Technical Implementation**:
1. Update template files:
   - `templates/issue-enhancement.template.md`
   - `templates/issue-bug.template.md`
   - `templates/epic.template.md`

2. Add classification field to frontmatter:
   ```yaml
   classification: {{CLASSIFICATION}}  # 1-10
   zone: {{ZONE}}  # ai-solo, ai-led, ai-assisted, ai-limited
   ```

3. Remove emoji risk indicators:
   - Search for 🟢 🟡 🔴 in all templates
   - Replace with classification field reference

4. Update docs/classification-guide.md with:
   - 1-10 scale explanation
   - Zone mapping rules
   - Examples for each level
```

**Dependencies:**
```markdown
**Dependencies**:
- **Depends on**: None (foundational change)
- **Blocks**: 
  - Issue 1.3: Add classification validation to scope-release
  - Issue 2.1: Add resource configuration schema
- **Related**: 
  - Spec § Epic 1: Classification Utilities Foundation
```

**Estimated Effort:**
```markdown
**Estimated Effort**:
- **Size**: Small (4-6 files, 50-100 lines changed)
- **Complexity**: Medium (requires template system understanding)
- **Time**: 2-3 hours for ai-led engineer
```

#### 3.4 Update current-release.md

Replace `<!-- TODO: enrich -->` markers with generated content:

```typescript
async function updateIssue(issueId: string, enrichedContent: EnrichedContent) {
  const content = await fs.readFile('memory-bank/releases/current-release.md', 'utf-8');
  
  // Find issue section
  const issueRegex = new RegExp(
    `#### Issue ${issueId}:.*?\\n\\n---`,
    's'
  );
  
  // Generate updated section
  const updatedSection = `
#### Issue ${issueId}: ${enrichedContent.title}

**Classification**: ${enrichedContent.classification} (${enrichedContent.zone})  
**Spec Reference**: ${enrichedContent.specReference}  
**Status**: ⏳ PENDING

**Overview & User Story**:
${enrichedContent.overview}

**Acceptance Criteria**:
${enrichedContent.acceptanceCriteria}

**Technical Implementation**:
${enrichedContent.technicalImplementation}

**Dependencies**:
${enrichedContent.dependencies}

**Estimated Effort**:
${enrichedContent.estimatedEffort}

---
  `.trim();
  
  // Replace in file
  const updated = content.replace(issueRegex, updatedSection);
  await fs.writeFile('memory-bank/releases/current-release.md', updated, 'utf-8');
}
```

### 4. Progress Display

Show real-time progress:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔬 ENRICHING RELEASE: v1.1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found 35 issues to enrich across 7 epics

Epic 1/7: Classification System Infrastructure
  ✅ Issue 1.1: Update issue templates (2.3s)
  ✅ Issue 1.2: Remove emoji risk indicators (1.8s)
  ⏳ Issue 1.3: Add classification validation...
```

### 5. Validation

After enrichment, validate:

```typescript
interface ValidationResult {
  totalIssues: number;
  enriched: number;
  needsEnrichment: number;
  incomplete: Array<{
    issueId: string;
    missingSections: string[];
  }>;
}
```

Display validation report:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ ENRICHMENT COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Status:
  ✅ Enriched:  35/35 issues (100%)
  ⏭️  Skipped:   0 issues (already enriched)
  ❌ Failed:    0 issues

All issues ready for /scope-release!

Next step: Run /scope-release --current to create GitHub issues
```

### 6. Handle --from Flag

If `--from` is specified:

```typescript
function parseIssueId(id: string): { epic: number; issue: number } {
  const [epic, issue] = id.split('.').map(Number);
  return { epic, issue };
}

function skipUntil(issues: Issue[], fromId: string): Issue[] {
  const { epic, issue } = parseIssueId(fromId);
  
  return issues.filter(i => {
    const iEpic = i.epicNumber;
    const iIssue = i.issueNumber;
    
    return iEpic > epic || (iEpic === epic && iIssue >= issue);
  });
}
```

### 7. Handle Existing Content

**Default behavior (--from without --force):**
- Skip issues that are already enriched
- Only enrich `<!-- TODO: enrich -->` sections

**With --force flag:**
- Overwrite all content, even if already enriched
- Useful for re-research after spec changes

```typescript
function needsEnrichment(section: string): boolean {
  return section.includes('<!-- TODO: enrich -->');
}

function shouldEnrich(issue: Issue, force: boolean): boolean {
  if (force) return true;
  
  return (
    needsEnrichment(issue.overview) ||
    needsEnrichment(issue.acceptanceCriteria) ||
    needsEnrichment(issue.technicalImplementation) ||
    needsEnrichment(issue.dependencies)
  );
}
```

## Research Quality Guidelines

**Overview & User Story:**
- 2-3 sentences explaining what and why
- User story format: As a... I want... So that...
- Context from spec and epic description

**Acceptance Criteria:**
- 3-6 specific, testable criteria
- Checkbox format
- Cover functional and non-functional requirements
- Include validation/error handling where applicable

**Technical Implementation:**
- Numbered steps or bulleted approach
- Specific file paths from tech-stack.md
- Code examples where helpful (especially for ai-led zones)
- Reference existing patterns in codebase

**Dependencies:**
- List prerequisite issues (must complete first)
- List blocked issues (waiting on this one)
- Note related issues for context
- Use "None" if truly independent

**Estimated Effort:**
- Size: Small/Medium/Large/XL
- Complexity: Low/Medium/High (based on classification)
- Time estimate based on zone (ai-solo: <1hr, ai-led: 1-4hrs, etc.)

## Error Handling

**Missing spec file:**
```
❌ Error enriching Epic 1: Spec file not found
   Path: context/specs/ai-issue-classification.md
   
   Please ensure the spec file exists and the path is correct.
```

**Spec section not found:**
```