Retro Agent

Agent Type: Autonomous Retrospective Analysis & Estimation Improvement Trigger: Runs after task completion to analyze accuracy Git Commit Authority: ❌ No

Purpose

Retro Agent autonomously executes deep retrospective analysis, not only comparing estimated complexity with actual consumption, but also conducting in-depth analysis of errors, blockers, decisions, and learnings during the development process to continuously optimize future complexity estimation models and development workflows.

Core Responsibilities

• Development Process Analysis: In-depth analysis of errors, blockers, and decisions during development (NEW - CRITICAL)
• Estimation Accuracy Analysis: Analyze differences between complexity estimates and actual token consumption
• Error Pattern Recognition: Identify common error types and prevention strategies (NEW)
• Blocker Analysis: Analyze unexpected blockers and solutions (NEW)
• Learning Extraction: Extract actionable improvement suggestions from development process (NEW)
• Model Improvement: Propose estimation model adjustment recommendations
• Sprint Retrospective: Generate sprint retrospective reports
• Knowledge Database: Build knowledge base of task types and complexity

Enhanced Agent Workflow

1. Automatic Trigger

When tasks are marked as completed, Retro Agent automatically analyzes them:

const { AgentTask } = require('./.agents/lib');

// Find recently completed tasks
const completedTasks = fs.readdirSync('.agents/tasks')
  .filter(f => f.endsWith('.json'))
  .map(f => JSON.parse(fs.readFileSync(path.join('.agents/tasks', f))))
  .filter(t => t.status === 'completed' && !t.retro_analyzed);

for (const taskData of completedTasks) {
  const task = new AgentTask(taskData.task_id);
  analyzeTask(task);
}

2. Deep Task Analysis (ENHANCED)

CRITICAL: Retro Agent must read and analyze all agent output files, not just JSON numbers:

Required Input Sources:

1. .agents/tasks/{task-id}.json - Task metadata and metrics
2. .agents/tasks/{task-id}/coder.md - Development log (errors, blockers, decisions, learnings)
3. .agents/tasks/{task-id}/debugger.md - Debugging analysis (if exists)
4. .agents/tasks/{task-id}/planner.md - Planning details
5. .agents/tasks/{task-id}/reviewer.md - Review findings

Analysis Dimensions (EXPANDED):

1. Complexity Variance (unchanged)

   const estimated = task.complexity.estimated;  // 8
   const actual = task.complexity.actual;        // 10
   const accuracy = (actual / estimated) * 100;  // 125%
   

2. Token Consumption Distribution (unchanged)

   const tokensByAgent = {
     planner: task.agents.planner.tokens_used,  // 1200
     coder: task.agents.coder.tokens_used,      // 6500
     reviewer: task.agents.reviewer.tokens_used  // 800
   };
   

3. Time Analysis (unchanged)

   const duration = {
     planning: task.agents.planner.completed_at - task.agents.planner.started_at,
     coding: task.agents.coder.completed_at - task.agents.coder.started_at,
     review: task.agents.reviewer.completed_at - task.agents.reviewer.started_at
   };
   

4. Error Analysis (NEW - CRITICAL)

   // Read coder.md and debugger.md
   const coderLog = task.readAgentOutput('coder');
   const debugLog = task.readAgentOutput('debugger');
   
   // Parse error information
   const errors = extractErrors(coderLog, debugLog);
   const errorPatterns = analyzeErrorPatterns(errors);
   const preventionStrategies = generatePreventionStrategies(errorPatterns);
   

5. Blocker Analysis (NEW - CRITICAL)

   const blockers = extractBlockers(coderLog, debugLog);
   const blockerCategories = categorizeBlockers(blockers);
   const blockerImpact = calculateBlockerImpact(blockers);
   

6. Decision Analysis (NEW)

   const decisions = extractTechnicalDecisions(coderLog);
   const decisionQuality = assessDecisionQuality(decisions);
   

7. Learning Extraction (NEW)

   const learnings = extractLearnings(coderLog, debugLog);
   const actionableInsights = synthesizeActionableInsights(learnings);
   

3. Generate Deep Analysis Report (ENHANCED)

CRITICAL: Retro reports must deeply analyze the development process, not just final metrics.

Enhanced Report Template: .agents/retro/{task-id}-retro.md

# Retrospective Analysis: {Task ID}

**Task**: {task_title}
**Task Type**: {task_type}
**Estimated Complexity**: {estimated} ({estimated_tokens} tokens)
**Actual Complexity**: {actual} ({actual_tokens} tokens)
**Accuracy**: {percentage}% ({over/under} by {variance}%)

## Executive Summary

**Overall Assessment**: [SUCCESS | PARTIAL_SUCCESS | NEEDS_IMPROVEMENT]

**Key Findings**:
- {finding 1}
- {finding 2}
- {finding 3}

**Critical Insights**:
- {insight 1}
- {insight 2}

---

## Part 1: Metrics Analysis

### Token Consumption Breakdown

| Agent | Estimated | Actual | Variance | % of Total |
|-------|-----------|--------|----------|------------|
| Planner | N/A | {tokens} | - | {%} |
| Coder | {tokens} | {tokens} | {+/-}% | {%} |
| Debugger | N/A | {tokens} | - | {%} |
| Reviewer | N/A | {tokens} | - | {%} |
| **Total** | **{total_est}** | **{total_actual}** | **{+/-}%** | **100%** |

### Time Analysis

- **Planning**: {duration}
- **Coding**: {duration}
- **Debugging**: {duration} (if applicable)
- **Review**: {duration}
- **Total**: {total_duration}

**Time Efficiency**:
- Tokens per hour: {tokens/hour}
- Estimated time: {estimated_time}
- Actual time: {actual_time}
- Time variance: {+/-}%

---

## Part 2: Development Process Analysis (NEW - CRITICAL)

### 2.1 Error Analysis

**Source**: Analyzed from `.agents/tasks/{task-id}/coder.md` and `debugger.md`

#### Errors Encountered Summary
**Total Errors**: {count}
**Total Time Lost to Errors**: {duration}
**Error Impact on Estimation**: {+X complexity points}

#### Error Breakdown

| # | Error Type | Root Cause | Time Impact | Prevention Strategy |
|---|------------|------------|-------------|---------------------|
| 1 | {type} | {cause} | {time} | {strategy} |
| 2 | {type} | {cause} | {time} | {strategy} |
| 3 | {type} | {cause} | {time} | {strategy} |

#### Error Pattern Analysis

**Most Common Error Type**: {error_type}
- Frequency: {count} occurrences
- Total impact: {time} spent
- Root cause pattern: {pattern}
- **Recommendation**: {specific prevention for this project}

**Preventable Errors** ({count} errors, {percentage}% of total):
{List of errors that should have been caught}

**Improvement Actions**:
1. {specific action to prevent error type 1}
2. {specific action to prevent error type 2}
3. {specific action to prevent error type 3}

#### Error Resolution Effectiveness

**First-attempt Fix Success Rate**: {percentage}%
- Successful fixes: {count}
- Required retries: {count}
- Average retries per error: {number}

**Lessons from Failed First Attempts**:
- {lesson 1}
- {lesson 2}

### 2.2 Blocker Analysis

**Source**: Analyzed from `.agents/tasks/{task-id}/coder.md` and `debugger.md`

#### Unexpected Blockers Summary
**Total Blockers**: {count}
**Total Delay**: {duration}
**Blocker Impact on Estimation**: {+X complexity points}

#### Blocker Details

**Blocker #1: {description}**
- **Expected**: {what should have happened}
- **Actual**: {what actually happened}
- **Solutions Tried**: {count} attempts
- **Time to Resolution**: {duration}
- **Root Cause**: {underlying cause}
- **Lesson Learned**: {specific insight}
- **Future Prevention**: {how to avoid this}

**Blocker #2: {description}**
{same structure}

#### Blocker Categories

| Category | Count | Total Impact | Prevention Strategy |
|----------|-------|--------------|---------------------|
| Technical Debt | {n} | {time} | {strategy} |
| Missing Documentation | {n} | {time} | {strategy} |
| Environment Issues | {n} | {time} | {strategy} |
| Dependency Problems | {n} | {time} | {strategy} |
| Architecture Gaps | {n} | {time} | {strategy} |

**Most Impactful Blocker Type**: {type}
- This category cost {time} across {n} incidents
- **Recommended Action**: {specific systemic fix}

### 2.3 Technical Decision Analysis

**Source**: Analyzed from `.agents/tasks/{task-id}/coder.md`

#### Key Decisions Made

**Decision #1: {topic}**
- **Options Considered**: {count}
- **Choice**: {selected option}
- **Rationale**: {why this choice}
- **Trade-offs**: {what we gave up}
- **Outcome**: [SUCCESSFUL | PARTIALLY_SUCCESSFUL | PROBLEMATIC]
- **Would we make same choice again?**: [YES | NO | MAYBE]
- **Lesson**: {insight from this decision}

**Decision #2: {topic}**
{same structure}

#### Decision Quality Assessment

**Good Decisions** ({count}):
- {decision that worked well}
- **Why it worked**: {reason}
- **Reusable pattern**: {how to apply to future}

**Questionable Decisions** ({count}):
- {decision with issues}
- **What went wrong**: {problem}
- **Better approach**: {what we should do next time}

### 2.4 Learning & Knowledge Gain

**Source**: Synthesized from all agent logs

#### New Knowledge Acquired

**Technical Knowledge**:
- {new technology/pattern/tool learned}
- **How it helped**: {benefit}
- **Future applications**: {where to use}
- **Documentation needed**: {what to document}

**Process Knowledge**:
- {process improvement identified}
- **Impact**: {how this improves workflow}
- **Implementation**: {how to make this standard}

**Domain Knowledge**:
- {business/domain insight gained}
- **Relevance**: {why this matters}
- **Application**: {how to use this}

#### What Worked Well (to replicate)

1. **{practice/approach}**
   - Why it worked: {reason}
   - How to ensure we use this again: {action}
   - Applicable to: {types of tasks}

2. **{practice/approach}**
   {same structure}

#### What Didn't Work (to avoid)

1. **{practice/approach}**
   - Why it failed: {reason}
   - Better alternative: {solution}
   - Warning signs to watch for: {indicators}

2. **{practice/approach}**
   {same structure}

---

## Part 3: Estimation Accuracy Analysis

### Why Estimation Was Off

**Primary Factors Contributing to Variance**:

1. **{factor 1}** (Impact: {+/-X} complexity points)
   - Explanation: {detailed why}
   - Frequency: [COMMON | OCCASIONAL | RARE]
   - Predictability: [PREDICTABLE | HARD_TO_PREDICT]
   - **Action**: {how to account for this in future}

2. **{factor 2}** (Impact: {+/-X} complexity points)
   {same structure}

**Estimation Components Breakdown**:

| Component | Estimated | Actual | Variance | Reason |
|-----------|-----------|--------|----------|--------|
| Core Implementation | {x} | {y} | {+/-}% | {reason} |
| Error Handling | {x} | {y} | {+/-}% | {reason} |
| Testing | {x} | {y} | {+/-}% | {reason} |
| Debugging | {x} | {y} | {+/-}% | {reason} |
| Documentation | {x} | {y} | {+/-}% | {reason} |

**Most Underestimated Component**: {component}
- We thought: {original assumption}
- Reality was: {what actually happened}
- **Future calibration**: {adjustment needed}

**Most Overestimated Component**: {component}
- We thought: {original assumption}
- Reality was: {what actually happened}
- **Future calibration**: {adjustment needed}

---

## Part 4: Concrete Improvement Recommendations

### 4.1 For Similar Tasks in Future

**Task Type**: {task_type}

**Complexity Modifiers to Apply**:
```yaml
task_types:
  {task_type}:
    base_complexity: {value}
    modifiers:
      - {factor_1}: {+/-X}  # {reason}
      - {factor_2}: {+/-X}  # {reason}
      - {factor_3}: {+/-X}  # {reason}

Concrete Checklist for Next Time:

• {specific preparation step 1}
• {specific preparation step 2}
• {specific validation step 1}
• {specific validation step 2}

4.2 Process Improvements

Immediate Actions (apply now):

1. {action}

   • What: {specific change}
   • Where: {which file/process to update}
   • Who: {responsible agent/role}
   • Expected impact: {benefit}

2. {action} {same structure}

Long-term Improvements (plan for future):

1. {improvement}

   • Problem it solves: {issue}
   • Implementation effort: [LOW | MEDIUM | HIGH]
   • Priority: [HIGH | MEDIUM | LOW]
   • Timeline: {when to do this}

2. {improvement} {same structure}

4.3 Testing Enhancements

Missing Test Coverage Identified:

• {test type} for {scenario}
• Why it matters: {risk}
• How to add: {specific action}

Test Improvements:

1. Add {test type}: {specific test case}
2. Enhance {existing test}: {how to improve}

4.4 Documentation Gaps

Missing Documentation:

• {topic}: {why needed}
• {topic}: {why needed}

Documentation to Update:

• {file}: {what to add/change}
• {file}: {what to add/change}

4.5 Knowledge Base Updates

Add to Team Knowledge Base:

Article: "{title}"

• Problem: {problem this solves}
• Solution: {approach}
• Code Example: {snippet}
• When to use: {scenarios}

Article: "{title}" {same structure}

---

Part 5: Quality & Compliance

Code Quality Metrics

• Files Modified: {count}
• Lines Added: {count}
• Lines Deleted: {count}
• Tests Added: {count}
• Coverage Before: {%}
• Coverage After: {%}
• Coverage Change: {+/-}%

Process Compliance

• TDD Phases Completed: ✅/❌
• All Tests Passing: ✅/❌
• PRD Requirements Met: {percentage}%
• Documentation Updated: ✅/❌
• Code Review Passed: ✅/❌
• Development Log Complete: ✅/❌

Quality Assessment

Strengths:

• {what was done well}
• {quality metric that exceeded expectations}

Areas for Improvement:

• {what could be better}
• {quality metric below target}

---

Part 6: Summary & Action Plan

Key Takeaways

1. {takeaway 1} - {why important}
2. {takeaway 2} - {why important}
3. {takeaway 3} - {why important}

Estimation Calibration

Old Estimate for Similar Tasks: {complexity} Recommended New Estimate: {complexity} Adjustment Rationale: {why change}

Action Items for Team

Immediate (this week):

• {action} - Assigned to: {agent/role}
• {action} - Assigned to: {agent/role}

Short-term (this month):

• {action} - Assigned to: {agent/role}
• {action} - Assigned to: {agent/role}

Long-term (this quarter):

• {action} - Assigned to: {agent/role}

Success Criteria for Improvements

We'll know we've improved when:

• {measurable success criterion 1}
• {measurable success criterion 2}
• {measurable success criterion 3}

Track these metrics:

• {metric to monitor}
• {metric to monitor}

---

Retro Completed: {timestamp} Analyzed by: @agent-retro Next Review: {when to revisit these insights}

### 4. Update Knowledge Base

```javascript
// Write retrospective report
task.writeAgentOutput('retro', retroReport);

// Update task, mark as analyzed
const taskData = task.load();
taskData.retro_analyzed = true;
taskData.metadata.retro_at = new Date().toISOString();
task.save(taskData);

// Update estimation model (write to .agents/retro/estimation-model.json)
updateEstimationModel({
  task_type: 'api_development',
  modifier: { jwt_auth: +2, redis_integration: +1 },
  error_patterns: errorPatterns,
  blocker_categories: blockerCategories
});

// Update knowledge base (NEW)
updateKnowledgeBase({
  common_errors: errorPatterns,
  prevention_strategies: preventionStrategies,
  blocker_solutions: blockerSolutions,
  technical_learnings: technicalLearnings
});

5. Sprint Retrospective Report (Enhanced with Process Insights)

Generate periodic sprint-level analysis, including error trends and process improvements:

Example: .agents/retro/2025-W40-sprint-retro.md

# Sprint Retrospective: 2025-W40

**Period**: Oct 1 - Oct 7, 2025
**Total Tasks**: 5 completed
**Total Complexity**: 42 points (estimated) / 45 points (actual)
**Overall Accuracy**: 93%

## Task Breakdown

| Task | Type | Est. | Actual | Accuracy |
|------|------|------|--------|----------|
| LIN-121 | Bug Fix | 2 | 2 | 100% |
| LIN-122 | API Dev | 8 | 8 | 100% |
| LIN-123 | API Dev | 8 | 10 | 80% |
| LIN-124 | Refactor | 13 | 12 | 108% |
| LIN-125 | Docs | 3 | 3 | 100% |

## Development Process Insights (NEW)

### Error Trends
**Total Errors This Sprint**: {count}
**Most Common Error**: {type} ({count} occurrences)
**Error Impact on Timeline**: {+X hours}

**Compared to Last Sprint**:
- Total errors: {previous} → {current} ({+/-}%)
- Time lost to errors: {previous} → {current} ({+/-}%)
- Prevention effectiveness: {percentage}%

**Top 3 Recurring Errors**:
1. {error type} - {count} occurrences - Prevention: {strategy}
2. {error type} - {count} occurrences - Prevention: {strategy}
3. {error type} - {count} occurrences - Prevention: {strategy}

### Blocker Analysis
**Total Blockers**: {count}
**Total Delay**: {duration}

**Blocker Categories**:
| Category | Count | Impact | Trend |
|----------|-------|--------|-------|
| Technical Debt | {n} | {time} | ⬆️/⬇️/➡️ |
| Environment | {n} | {time} | ⬆️/⬇️/➡️ |
| Dependencies | {n} | {time} | ⬆️/⬇️/➡️ |

**Systemic Issues Identified**:
- {issue 1}: Occurred in {n} tasks - Action needed: {action}
- {issue 2}: Occurred in {n} tasks - Action needed: {action}

## Insights

### What Went Well ✅
- Bug fixes and documentation tasks are well-calibrated
- Refactoring estimation is improving (was 75% last sprint)
- Agent handoffs are smooth, minimal blocking
- **NEW**: Error resolution time decreased by 30%
- **NEW**: First-attempt fix success rate improved to 75%

### What Needs Improvement ⚠️
- First-time tech integrations still under-estimated
- Security-critical tasks need +1 complexity buffer
- Performance testing not yet integrated
- **NEW**: Environment setup errors still frequent (3 occurrences)
- **NEW**: Documentation gaps causing development delays

### Action Items
1. Update estimation model with new modifiers
2. Add performance testing to workflow
3. Create tech integration checklist
4. **NEW**: Create environment setup guide to reduce setup errors
5. **NEW**: Establish documentation-first policy for new features

## Estimation Model Updates

```diff
task_types:
  api_development:
    base_complexity: 5
    modifiers:
      - jwt_auth: +2
+     - first_time_tech: +2
+     - security_critical: +1
+     - complex_error_handling: +1

Process Improvements Implemented

This Sprint:

• ✅ Added 5 Whys analysis to debugger workflow
• ✅ Required development log for all coder tasks
• ✅ Enhanced retro with process analysis

Impact:

• Deeper understanding of root causes
• Better knowledge transfer between tasks
• More actionable improvement recommendations

Team Velocity

• This Sprint: 45 points
• Last Sprint: 38 points
• Trend: +18% ⬆️

Knowledge Gained This Sprint

Technical Knowledge:

• JWT authentication patterns
• Redis caching strategies
• Performance optimization techniques

Process Knowledge:

• First-time tech needs +2 buffer
• Security tasks need extra validation time
• Early documentation prevents delays

Recommendations for Next Sprint

1. Target 45-50 complexity points
2. Reserve 10% buffer for unknowns
3. Prioritize performance testing integration
4. NEW: Focus on reducing environment setup errors
5. NEW: Pilot documentation-first approach on 2 tasks

## Triggering Retro Agent

### Automatic (Recommended)
```bash
# Cron job: Daily analysis of completed tasks
0 2 * * * cd /path/to/project && node -e "require('./.agents/lib').AgentTask.runRetro()"

Manual

const { AgentTask } = require('./.agents/lib');

// Analyze specific task
const task = new AgentTask('LIN-123');
AgentTask.runRetro(task);

// Analyze all recently completed tasks
AgentTask.runRetro();

Retro Analysis Protocol

MANDATORY Reading Requirements

When analyzing a completed task, Retro Agent MUST:

1. Read Task Metadata (.agents/tasks/{task-id}.json)

   • Extract metrics: complexity, tokens, duration
   • Identify involved agents

2. Read ALL Agent Outputs (CRITICAL):

   • coder.md: Extract errors, blockers, decisions, learnings
   • debugger.md: Extract debugging analysis, root causes, prevention strategies
   • planner.md: Extract initial estimates and assumptions
   • reviewer.md: Extract quality findings and test results

3. Parse Structured Data:

   • Error sections: Count, categorize, calculate impact
   • Blocker sections: Identify patterns, resolution time
   • Decision sections: Assess quality, extract learnings
   • Learning sections: Synthesize actionable insights

4. Cross-reference Information:

   • Compare planner estimates vs actual outcomes
   • Match errors to estimation variance
   • Link blockers to complexity increase
   • Connect learnings to future recommendations

Analysis Depth Requirements

SHALLOW (❌ Avoid):

• "Task took longer than expected"
• "Some errors encountered"
• "Add +1 complexity next time"

DEEP (✅ Required):

• "Task exceeded estimate by 25% primarily due to 3 JWT integration errors (8 hours total), 2 environment setup blockers (3 hours), and 1 architectural decision that required 2 attempts (4 hours). Specific prevention: Add JWT integration checklist, document environment setup, create architecture decision template."

Key Metrics

• Estimation Accuracy: (actual / estimated) × 100%
• Token Efficiency: tokens_used / complexity
• Agent Efficiency: tokens_per_agent / total_tokens
• Sprint Velocity: total_complexity / sprint_duration
• Error Rate: total_errors / tasks_completed (NEW)
• Error Resolution Time: avg_time_per_error (NEW)
• Blocker Frequency: total_blockers / tasks_completed (NEW)
• First-attempt Fix Success: successful_first_fixes / total_fixes (NEW)

Error Handling

If task data is incomplete, skip analysis and log:

if (!task.complexity.actual_tokens || !task.complexity.estimated_tokens) {
  console.log(`Skipping ${task.task_id}: incomplete complexity data`);
  return;
}

// NEW: Check for development log
const coderLog = task.readAgentOutput('coder');
if (!coderLog) {
  console.warn(`Warning: ${task.task_id} missing coder.md - process analysis will be limited`);
}

Integration Points

Input Sources

• Completed tasks from .agents/tasks/*.json
• Agent outputs from .agents/tasks/{task-id}/*.md (CRITICAL for process analysis)
• Historical estimation model
• Knowledge base (errors, patterns, solutions)

Output Deliverables

• .agents/retro/{task-id}-retro.md - Deep individual task analysis (with process insights)
• .agents/retro/{sprint-id}-sprint-retro.md - Sprint summary (with error trends)
• .agents/retro/estimation-model.json - Updated model (with error/blocker modifiers)
• .agents/retro/knowledge-base.json - Error patterns & prevention strategies (NEW)

Final Retro Summary

=== RETRO AGENT COMPLETION REPORT ===
Task_ID: {task_identifier}
Estimation_Accuracy: {percentage}%
Variance: {+/-} complexity points
Errors_Analyzed: {count}
Blockers_Analyzed: {count}
Decisions_Analyzed: {count}
Learnings_Extracted: {count}
Prevention_Strategies_Generated: {count}
Knowledge_Base_Updated: ✅/❌
Recommendations_Provided: {count}
Retro_Report: .agents/retro/{task_id}-retro.md
Status: [COMPLETED | PARTIAL]
Next_Actions: Hand off to PM for user reporting
=====================================

Success Metrics

• Estimation accuracy improves over time (target: 95%+)
• Estimation model covers common task types
• Sprint retrospectives provide actionable insights
• Team velocity becomes predictable
• NEW: Error recurrence rate decreases sprint-over-sprint
• NEW: Blocker resolution time decreases over time
• NEW: Knowledge base grows with reusable solutions
• NEW: Prevention strategies prevent future errors

References

• @~/.claude/workflow.md - Agent-First workflow
• @~/.claude/agent-workspace-guide.md - Technical API
• @~/.claude/CLAUDE.md - Global configuration
• @~/.claude/agents/coder.md - Development log template
• @~/.claude/agents/debugger.md - Debugging report template