# Path detection for .parade/ structure
if [ -f ".parade/discovery.db" ]; then
  DISCOVERY_DB=".parade/discovery.db"
else
  DISCOVERY_DB="./discovery.db"
fi

bd show <epic-id> --json

# Get recently closed epics
bd list -t epic --status closed --json | head -n <n>

// Read via TelemetryService
const summary = TelemetryService.getEpicSummary(epicId);

## Retrospective: <epic-id>

Insufficient data for analysis.

The telemetry file `.claude/metrics/<epic-id>.json` was not found or contains no execution data.

This can happen if:
- The epic was created before telemetry was enabled
- Execution was interrupted before metrics were captured
- The metrics file was manually deleted

Options:
1. Skip retrospective and close epic
2. Generate a basic summary from beads data only

// 1. Epic summary from telemetry
const telemetry = TelemetryService.getEpicSummary(epicId);

// 2. Task list from beads
const tasks = await exec('bd list --parent <epic-id> --json');

// 3. Existing debug knowledge patterns
const patterns = await glob('.claude/debug-knowledge/*.md');

// 4. Existing insights
const insights = await readIfExists('.claude/retrospectives/INSIGHTS.md');

function calculateEfficiencyScore(summary: EpicSummary): number {
  let score = 10;

  // Penalty for debug loops
  score -= summary.totalDebugLoops;

  // Penalty for blocked tasks
  score -= summary.blockedTasks * 2;

  // Bonus for clean execution
  if (summary.totalDebugLoops === 0 && summary.blockedTasks === 0) {
    score += 1;
  }

  return Math.max(1, score);
}

interface AnalysisResult {
  debugPatterns: DebugPattern[];      // Repeated failure types
  agentIssues: AgentIssue[];          // Agent-specific problems
  workflowFriction: FrictionPoint[];  // Process bottlenecks
}

function analyzePatterns(summary: EpicSummary): AnalysisResult {
  const patterns: DebugPattern[] = [];

  // Group debug sessions by error type
  for (const debug of summary.debugSessions) {
    const existing = patterns.find(p => p.errorType === debug.errorType);
    if (existing) {
      existing.count++;
      existing.tasks.push(debug.taskId);
    } else {
      patterns.push({
        errorType: debug.errorType,
        count: 1,
        tasks: [debug.taskId],
        resolution: debug.resolution
      });
    }
  }

  return { debugPatterns: patterns, agentIssues: [], workflowFriction: [] };
}

### Agent Prompt: <agent-type>

**Issue**: <description of failure pattern>
**Frequency**: <N> occurrences

**Suggested Addition**:
```diff
# .claude/agents/<agent-type>.md
+ ## Common Pitfalls
+ - <specific warning based on failure>

#### 6b. Debug Knowledge Entries

For each new pattern discovered:
```markdown
### Debug Knowledge: <pattern-name>

**Pattern**: <slug-for-filename>
**Symptom**: <error message or behavior>
**Cause**: <root cause from debug resolution>
**Fix**: <solution that worked>

**Suggested File**: `.claude/debug-knowledge/<pattern>.md`

### Workflow Config

**Issue**: <systemic problem>
**Recommendation**: <config change>

**Suggested Update**:
```yaml
# project.yaml
workflow:
  <setting>: <new-value>

### Step 7: Present Report for Approval

Display the complete analysis:

```markdown
## Retrospective Analysis: <epic-id>

### Executive Summary
- **Epic**: <title>
- **Tasks**: <completed>/<total> (<blocked> blocked)
- **Debug Loops**: <count>
- **Efficiency Score**: <score>/10

### Analysis

#### What Went Well
- <positive observation 1>
- <positive observation 2>

#### Areas for Improvement
- <issue 1>: <brief description>
- <issue 2>: <brief description>

### Recommendations

<recommendations from Step 6>

---

**Approval Required**

Which changes should be applied?

1. Apply all recommendations
2. Apply selectively (I'll specify which)
3. Skip all changes (archive report only)
4. Cancel retrospective

---

**DRY RUN: No files were modified**

This was a preview of the retrospective analysis. To apply changes, run:
`/retro <epic-id>` (without --dry-run)

# Append to agent file
cat >> .claude/agents/<agent-type>.md << 'EOF'

## Common Pitfalls
- <new pitfall warning>
EOF

# Create new debug knowledge file
cat > .claude/debug-knowledge/<pattern>.md << 'EOF'
# <Pattern Name>

## Symptom
<symptom description>

## Cause
<root cause>

## Fix
<solution>

## Source
Discovered during epic: <epic-id>
EOF

mkdir -p .claude/retrospectives

cat > .claude/retrospectives/<epic-id>.md << 'EOF'
# Retrospective: <epic-id>

**Date**: <date>
**Efficiency Score**: <score>/10

## Summary
- Tasks: <completed>/<total>
- Debug Loops: <count>
- Blocked: <count>

## Findings
<analysis content>

## Changes Applied
- [ ] <change 1> - Applied/Skipped
- [ ] <change 2> - Applied/Skipped

## Recommendations Deferred
<any skipped recommendations for future consideration>
EOF

cat >> .claude/retrospectives/INSIGHTS.md << 'EOF'

## Epic: <epic-id> (<date>)
- **Score**: <score>/10
- **Key Learning**: <one-line summary>
- **Patterns Added**: <list of new debug-knowledge entries>
EOF

# Workflow Insights

Accumulated learnings from epic retrospectives.

---

# Retrospective: <epic-id>

**Date**: YYYY-MM-DD
**Efficiency Score**: N/10

## Executive Summary

| Metric | Value |
|--------|-------|
| Tasks Completed | X/Y |
| Tasks Blocked | Z |
| Debug Loops | N |
| Token Estimate | ~NK |

## Task Breakdown

| Task | Status | Attempts | Notes |
|------|--------|----------|-------|
| <id> | closed | 1 | First try |
| <id> | closed | 2 | Debug: null check |
| <id> | blocked | 3 | Max attempts |

## Patterns Identified

### <Pattern Name>
- **Occurrences**: N
- **Resolution**: <how it was fixed>
- **Prevention**: <how to avoid in future>

## Recommendations

### Immediate
- [ ] <actionable item>

### For Future Epics
- [ ] <consideration for similar work>

## Changes Applied
- <list of files modified>

## Retrospective: <epic-id>

**Limited Analysis Mode**

Telemetry data unavailable. Analysis based on beads data only.

### Available Information
- Tasks: <from bd list>
- Final status: <from bd show>

### Unable to Determine
- Debug loop count
- Token usage
- Failure patterns

Recommendation: Enable telemetry capture for future epics.

## Retrospective: <epic-id>

**Efficiency Score**: 11/10 (Perfect execution bonus)

All tasks completed on first attempt with no debug loops or blocked tasks.

### Analysis
No issues to address. Current workflow configuration is working well for this type of feature.

### Optional
- Archive this as a reference for similar features
- Note the task structure for reuse

## Retrospective Summary: Last N Epics

| Epic | Score | Debug | Blocked | Key Issue |
|------|-------|-------|---------|-----------|
| <id> | 8/10 | 2 | 0 | State binding |
| <id> | 10/10 | 0 | 0 | Clean |
| <id> | 6/10 | 3 | 1 | Type errors |

### Cross-Epic Patterns
- <pattern> appeared in N epics
- <agent> had issues in N epics

### Consolidated Recommendations
<merged recommendations addressing multiple epics>

## Retrospective Analysis: bd-x7y8

### Executive Summary
- **Epic**: Athlete Experience Tracking
- **Tasks**: 4/5 completed (1 blocked)
- **Debug Loops**: 2
- **Efficiency Score**: 5/10

### Analysis

#### What Went Well
- Database schema task completed first try
- UI components rendered correctly

#### Areas for Improvement
- SwiftUI state binding caused 2 debug loops
- TypeScript null check missing in edge function

### Recommendations

#### Agent Prompt: swift-agent
**Issue**: State binding errors in child views
**Suggested Addition**:
```diff
+ ## Common Pitfalls
+ - Use @Binding in child views, not @State
+ - Initialize state before view body

**User:** 1

**Claude:**

### Example 2: Clean Execution

**User:** /retro bd-a1b2

**Claude:**
```markdown
## Retrospective Analysis: bd-a1b2

### Executive Summary
- **Epic**: Task List Filter
- **Tasks**: 3/3 completed
- **Debug Loops**: 0
- **Efficiency Score**: 11/10

All tasks completed on first attempt. No issues to address.

Options:
1. Archive this retrospective
2. Skip (no archive)

All tasks for "User Authentication" are complete.

Completed: 6 tasks
Blocked: 0 tasks
Debug loops: 3

Options:
1. Merge and close epic
2. Merge and close with retrospective (recommended - debug loops detected)
3. Keep open for manual review

## Retrospective: bd-old1

**Limited Analysis Mode**

Telemetry data not found for this epic. This epic may predate telemetry capture.

### Available Information (from beads)
- Tasks: 4 total, 4 closed
- Created: 2024-01-15
- Type: Epic

### Recommendation
For future epics, ensure telemetry capture is enabled in project.yaml:

```yaml
workflow:
  retrospective:
    capture_metrics: true

### Example 5: Dry Run Preview

**User:** /retro bd-x7y8 --dry-run

**Claude:**
```markdown
## Retrospective Analysis: bd-x7y8

### Executive Summary
- **Epic**: Athlete Experience Tracking
- **Tasks**: 4/5 completed (1 blocked)
- **Debug Loops**: 2
- **Efficiency Score**: 5/10

### Analysis

#### What Went Well
- Database schema task completed first try
- UI components rendered correctly

#### Areas for Improvement
- SwiftUI state binding caused 2 debug loops
- TypeScript null check missing in edge function

### Recommendations

#### Agent Prompt: swift-agent
**Issue**: State binding errors in child views
**Suggested Addition**:
```diff
+ ## Common Pitfalls
+ - Use @Binding in child views, not @State
+ - Initialize state before view body

---

## Files Modified

This skill may create or modify:

| Path | Action | Approval |
|------|--------|----------|
| `.claude/retrospectives/<epic-id>.md` | Create | Automatic |
| `.claude/retrospectives/INSIGHTS.md` | Append | Automatic |
| `.claude/debug-knowledge/<pattern>.md` | Create | Required |
| `.claude/agents/<agent>.md` | Append | Required |
| `project.yaml` | Modify | Required |

---

## Configuration

```yaml
# project.yaml
workflow:
  retrospective:
    # Trigger conditions
    prompt_frequency: 3          # Offer every N epics
    prompt_on_debug: true        # Always offer if debug loops
    prompt_on_blocked: true      # Always offer if blocked tasks

    # Data capture (during /run-tasks)
    capture_metrics: true
    capture_token_estimates: true

    # Storage locations
    metrics_dir: .claude/metrics
    retrospectives_dir: .claude/retrospectives
    insights_file: .claude/retrospectives/INSIGHTS.md

    # Auto-apply (vs require approval)
    auto_apply:
      debug_knowledge: true      # New pattern files
      agent_prompts: false       # Require approval
      workflow_config: false     # Require approval

# In run-tasks Step 10
if user_choice == 2:  # "Merge and close with retrospective"
    # Run retrospective before merge
    await invoke_skill('retro', epic_id)

    # Then proceed with merge
    await merge_and_close_epic(epic_id)