retro

name: retro description: Analyze epic execution and generate improvement recommendations. Reads telemetry data, calculates efficiency score, and proposes workflow improvements. Use after epic completion or to review recent executions.

Retro Skill

Purpose

Analyze completed epic executions and generate actionable recommendations for workflow improvement. The retrospective process:

1. Reads execution telemetry from TelemetryService
2. Calculates an efficiency score based on debug loops and blocked tasks
3. Generates specific recommendations for agent prompts, debug knowledge, and workflow config
4. Requires user approval before applying any changes
5. Archives the retrospective for future reference

When to Use

• User invokes /retro <epic-id> directly
• User invokes /retro --recent [n] to review recent epics
• User selects Option 2 at /run-tasks Step 10 (epic completion)
• After any epic with debug loops or blocked tasks
• Periodically to review accumulated patterns

Entry Points

Arguments

Process

Step 0: Path Detection

Determine the location of discovery.db to support both new .parade/ structure and legacy project root:

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

All subsequent database operations in this skill use $DISCOVERY_DB instead of hardcoded discovery.db.

Step 1: Resolve Epic Context

Determine which epic(s) to analyze based on invocation:

For /retro <epic-id>:

bd show <epic-id> --json

Validate the epic exists and has status closed or all child tasks closed.

For /retro --recent [n]:

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

From /run-tasks Step 10: Epic ID is passed from the completion context.

Step 2: Check for Sufficient Data

Before proceeding, verify telemetry exists:

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

If no telemetry data exists:

## 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

If user selects option 2, proceed with limited analysis using only beads data.

Step 3: Gather Context (Token-Efficient)

Read only essential data (~500 tokens total):

// 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');

Do NOT:

• Re-read source code files
• Re-read full task descriptions
• Load agent output files
• Read git history beyond summary

Step 4: Calculate Efficiency Score

Base Score: 10

Apply adjustments:

• -1 per debug loop (task required debug-agent spawn)
• -2 per blocked task (task ended in blocked status)
• +1 if all tasks passed on first attempt (no debug loops)

Minimum score: 1

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);
}

Step 5: Analyze Patterns

Identify recurring issues from telemetry:

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: [] };
}

Step 6: Generate Recommendations

Create structured recommendations in three categories:

6a. Agent Prompt Improvements

For each agent that had failures:

### 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`

6c. Workflow Config Updates

For systemic issues:

### 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 Mode

When --dry-run is specified, present the report and then skip to completion:

---

**DRY RUN: No files were modified**

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

In dry-run mode:

• Skip Step 8 (Apply Approved Changes)
• Skip Step 9 (Archive Retrospective)
• Skip Step 10 (Update Accumulated Insights)

No approval prompt is shown since no changes will be applied.

Step 8: Apply Approved Changes

For each approved change:

Agent Prompt Updates

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

## Common Pitfalls
- <new pitfall warning>
EOF

Debug Knowledge Entries

# 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

Workflow Config Updates

Require explicit confirmation before modifying project.yaml.

Step 9: Archive Retrospective

Write the full retrospective to archive:

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

Step 10: Update Accumulated Insights

Append to the insights file:

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

If INSIGHTS.md doesn't exist, create with header:

# Workflow Insights

Accumulated learnings from epic retrospectives.

---

Output Format

Retrospective Report

# 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>

Handling Edge Cases

Insufficient Data

When telemetry is missing or incomplete:

## 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.

No Issues Found

When execution was flawless:

## 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

Multiple Epics (--recent)

When analyzing multiple epics:

## 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>

Token Budget

Target: ~2000 tokens total for retrospective

Efficiency principle: The 2K token investment should prevent 5-10K in future debug loops.

Example Interactions

Example 1: Standard Retrospective

User: /retro bd-x7y8

Claude:

## 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

Debug Knowledge: swiftui-state-binding

Pattern: swiftui-state-binding Symptom: View not updating on state change Cause: @State used in child view instead of @Binding Fix: Change @State to @Binding, pass from parent

Approval Required

Which changes should be applied?

1. Apply all recommendations
2. Apply selectively
3. Skip all (archive only)
4. Cancel

**User:** 1

**Claude:**

Applying changes...

• Updated: .claude/agents/swift-agent.md
• Created: .claude/debug-knowledge/swiftui-state-binding.md
• Archived: .claude/retrospectives/bd-x7y8.md
• Updated: .claude/retrospectives/INSIGHTS.md

Retrospective complete.

### 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)

Example 3: From /run-tasks Completion

Claude (at Step 10):

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

User: 2

Claude: [Proceeds with retrospective flow, then merge]

Example 4: Insufficient Data

User: /retro bd-old1

Claude:

## 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

Options:

1. Generate basic summary from beads only
2. Skip retrospective

### 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

Debug Knowledge: swiftui-state-binding

Pattern: swiftui-state-binding Symptom: View not updating on state change Cause: @State used in child view instead of @Binding Fix: Change @State to @Binding, pass from parent

DRY RUN: No files were modified

This was a preview of the retrospective analysis. To apply changes, run: /retro bd-x7y8 (without --dry-run)

---

## 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

Integration with /run-tasks

The retrospective skill is invoked from /run-tasks Step 10 when user selects Option 2:

# 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)

The retrospective runs inline, allowing the user to review and approve changes before the epic is finalized.