# Issue #336-340 Closure Fix & Prevention Guide

**Date**: 2025-10-29 | **Status**: RESOLVED ✅ | **Recurring Problem**: Fixed

## Problem Statement

When PR #365 merged to main (closing Epic #360), **only the epic issue (#360) closed**, but the 5 child issues (#336-340) remained open. This is the 3rd-4th occurrence of this problem.

## Root Cause

**The PR body only included `Closes #360`** but didn't include the child issues:

```markdown
# ❌ INCORRECT (what was done)
Closes #360
```

GitHub's auto-close feature requires **explicit `Closes #N` keywords for EACH issue**. Without them, only issues explicitly mentioned are closed on merge.

## Solution Applied

**Manually closed all 5 child issues** via GitHub API:
- ✅ Issue #336 - Closed
- ✅ Issue #337 - Closed
- ✅ Issue #338 - Closed
- ✅ Issue #339 - Closed
- ✅ Issue #340 - Closed

## Proper Pattern for Future PRs

### For Epic-Based Work (Multiple Linked Issues)

**CORRECT PR Body Template:**

```markdown
## [Epic Name] Implementation Complete

Description of work...

### Closes

Closes #[EPIC]
Closes #[CHILD_1]
Closes #[CHILD_2]
Closes #[CHILD_3]
Closes #[CHILD_4]
Closes #[CHILD_5]
```

### Example for Epic #360

```markdown
## Epic #360: Scripts Folder Organization & Consolidation

All 5 child issues implemented and merged.

### Closes

Closes #360
Closes #336
Closes #337
Closes #338
Closes #339
Closes #340
```

### Implementation Pattern

When creating release PRs (dev → main) with epics:

```javascript
// DO THIS in PR creation code:
const closesList = [epicNumber, ...childIssues].map(n => `Closes #${n}`).join('\n');

// Result:
// Closes #360
// Closes #336
// Closes #337
// ... etc
```

## How It Works

**GitHub's Auto-Close Rules:**
1. When PR is merged to main
2. GitHub scans PR body for keywords: `Closes`, `Fixes`, `Resolves`
3. For each `Closes #N` found: issue #N is automatically closed
4. If a keyword appears for an issue: it's closed on merge
5. If NO keyword appears: issue remains open

## Prevention Checklist

For future epic-based PRs:

- [ ] PR body includes `Closes #[EPIC]` for main epic
- [ ] PR body includes `Closes #[CHILD_N]` for **EACH** child issue
- [ ] All linked issues will auto-close when PR merges
- [ ] Test: Verify all issues close after merge
- [ ] If any issue remains open: manually close + investigate

## Recommended Automation

### Option 1: Update autopilot.md Template

Modify the autopilot command to auto-generate the Closes list:

```bash
# When creating release PR, generate Closes for epic + children
CLOSES_LIST=$(echo "Closes #${EPIC_NUMBER}" && \
  for issue in "${CHILD_ISSUES[@]}"; do
    echo "Closes #${issue}"
  done)

# Include in PR body:
PR_BODY="...${CLOSES_LIST}..."
```

### Option 2: Create Issue Closure Script

Add `scripts/close-epic-issues.ts` to handle closure automatically:

```typescript
async function closeEpicAndChildren(epicNumber: number) {
  // Get child issues via GitHub API
  // Create PR with all Closes keywords
  // Verify all close on merge
}
```

### Option 3: GitHub Workflow Automation

Create `.github/workflows/auto-close-epic-children.yml`:

```yaml
name: Auto-close Epic Children
on:
  pull_request:
    types: [closed]
if: github.event.pull_request.merged == true
jobs:
  close-children:
    # Find epic in PR body
    # Extract child issues
    # Close all children
```

## Impact Assessment

**Current State**: Fixed for Epic #360
- All 5 child issues now closed ✅
- Epic #360 closed ✅

**Future Prevention**: Implement one of the automation options above

**Risk**: Recurring problem if not addressed in autopilot/PR templates

## Recommended Action

### Immediate (For Phase 2 Epics)

Update the PR creation code in autopilot.md to include:

```markdown
## Closes

Closes #[EPIC_NUMBER]
Closes #[CHILD_1]
Closes #[CHILD_2]
... etc
```

### Medium-term (1-2 weeks)

Create `scripts/close-epic-issues.ts` to automate closure list generation

### Long-term (Next sprint)

Integrate into GitHub Actions workflow for automatic validation

## Historical Context

This issue has occurred 3-4 times previously because:
1. PR creation templates don't include child issues
2. autopilot.md only mentions epic closure, not children
3. No validation/verification step after PR merge
4. Manual process prone to human error

**Fix**: Automate + document + validate

## References

- GitHub Docs: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
- autopilot.md: See section on PR creation
- Epic #360: Issue closure workflow
- Future: Epic #366/#367 should implement closure automation

---

**Status**: Issue Resolved + Pattern Documented  
**Next**: Implement automation to prevent recurrence