---
name: scorpio-retro
description: Analyze completed development cycles to extract lessons learned, identify recurring patterns, and improve future workflows. Use after shipping a feature, completing a sprint, or finishing a QA rework loop to capture what worked and what didn't.
---

# Retrospective

A structured methodology for analyzing completed development cycles and feeding lessons back into the system. This skill closes the learning loop — each cycle makes the next one better.

## When to Use

- After a feature branch is merged (end of a full cycle)
- After completing a batch of tasks
- After a particularly difficult QA rework loop
- Periodically (weekly/monthly) for ongoing projects
- When the same types of issues keep recurring

## Prerequisites

To run a retrospective, you need access to:
- Completed task files (in `done/`)
- QA reports (in `qa-reports/`)
- Rework task files (if any)
- Git log for the feature branch
- Any triage summaries from scorpio-qa-rework

## Retrospective Phases

```
Phase 1: Gather    → Collect data from the completed cycle
Phase 2: Analyze   → Identify patterns, surprises, and recurring issues
Phase 3: Extract   → Distill actionable insights
Phase 4: Recommend → Suggest process and convention improvements
Phase 5: Record    → Persist learnings for future reference
```

## Phase 1: Gather

Collect quantitative and qualitative data from the cycle.

### Data Sources

| Source | What to Extract |
|--------|----------------|
| Task files (done/) | Task count, types, estimates, dependencies |
| QA reports | Finding count by severity, pass/fail rates |
| Rework tasks | Rework count, what caused them |
| Git log | Commit count, commit frequency, branch lifespan |
| Triage summaries | Decision patterns, deferral count |

### Gather Template

```markdown
## Cycle Data

### Tasks
- **Total tasks**: [N]
- **By type**: [N] Feature, [N] Bug, [N] Chore
- **By estimate**: [N] XS, [N] S, [N] M, [N] L

### QA Results
- **First-pass approval rate**: [N]% ([N] of [N] tasks passed on first QA)
- **Total QA cycles**: [N] across all tasks
- **Findings by severity**: [N] Critical, [N] High, [N] Medium, [N] Low
- **Findings by category**: [N] Correctness, [N] Security, [N] Performance, [N] Patterns, [N] Testing

### Rework
- **Rework tasks generated**: [N]
- **Rework cycles**: [N] tasks needed 1 rework, [N] needed 2, [N] needed 3+
- **Most common rework reason**: [category]

### Git
- **Total commits**: [N]
- **Branch lifespan**: [N] days
- **Average commits per task**: [N]

### Timeline
- **Planning completed**: [date]
- **Development started**: [date]
- **First QA pass**: [date]
- **All tasks approved**: [date]
- **Released**: [date]
```

## Phase 2: Analyze

Look for patterns, surprises, and root causes in the data.

### Pattern Detection

#### QA Failure Patterns

```markdown
### QA Failure Analysis

| Pattern | Occurrences | Tasks Affected |
|---------|-------------|---------------|
| Missing error handling | [N] | [task list] |
| Incomplete acceptance criteria | [N] | [task list] |
| Security: unvalidated input | [N] | [task list] |
| Missing tests | [N] | [task list] |
| Logic errors | [N] | [task list] |
```

**Questions to answer:**
- Are the same finding categories appearing across multiple tasks?
- Is one module or area generating more QA findings than others?
- Are certain task types (Feature vs Bug vs Chore) failing QA more often?

#### Estimation Accuracy

```markdown
### Estimation Analysis

| Estimated | Actual Effort | Count | Trend |
|-----------|--------------|-------|-------|
| XS | XS | [N] | Accurate |
| S | S | [N] | Accurate |
| S | M | [N] | Underestimated |
| M | M | [N] | Accurate |
| M | L | [N] | Underestimated |
```

**Questions to answer:**
- Are estimates consistently optimistic or pessimistic?
- Which task types are hardest to estimate?
- Are certain areas of the codebase consistently slower to work in?

#### Rework Root Causes

```markdown
### Rework Root Cause Analysis

| Root Cause | Count | Could Have Been Prevented By |
|-----------|-------|------------------------------|
| Vague acceptance criteria | [N] | Clearer task specs |
| Missing edge case in design | [N] | Better validation phase |
| Convention not followed | [N] | Convention documented in CLAUDE.md |
| Integration issue | [N] | Better dependency tracking |
```

#### Positive Patterns

Don't just look at failures — identify what worked:

```markdown
### What Worked Well

- [Pattern that led to first-pass QA approval]
- [Practice that sped up development]
- [Convention that prevented issues]
```

## Phase 3: Extract

Distill the analysis into actionable insights.

### Insight Categories

| Category | Description | Example |
|----------|-------------|---------|
| **Process** | How the workflow could improve | "Self-QA missed error handling 4 times — add it to the self-QA checklist" |
| **Convention** | Coding standards to add/update | "All API endpoints should validate input — add to CLAUDE.md" |
| **Estimation** | Calibration adjustments | "Tasks involving the auth module consistently take 1.5x estimate" |
| **Tooling** | Tool or config improvements | "ESLint rule for no-unhandled-promises would have caught 3 findings" |
| **Documentation** | Docs that would have helped | "The payment flow needs a sequence diagram — devs kept getting it wrong" |
| **Task Quality** | How task specs could improve | "Bug fix tasks without reproduction steps led to 2x rework" |

### Insight Format

```markdown
### Insight: [Title]

**Category**: Process | Convention | Estimation | Tooling | Documentation | Task Quality
**Evidence**: [N] occurrences across [task list]
**Impact**: High | Medium | Low

**What happened**: [1-2 sentences describing the pattern]

**What to change**: [Specific, actionable recommendation]

**Apply to**: [CLAUDE.md | QA checklist | task template | estimation guide | etc.]
```

## Phase 4: Recommend

Convert insights into specific recommendations, prioritized by impact.

### Recommendation Types

#### Convention Updates (→ CLAUDE.md / project docs)

```markdown
### Recommended Convention Updates

| # | Convention | Add To | Rationale |
|---|-----------|--------|-----------|
| 1 | All API endpoints must validate request body | CLAUDE.md | 4 QA findings for missing validation |
| 2 | Error responses must include user-friendly message | CLAUDE.md | 3 tasks had generic error messages |
| 3 | New components require loading + error states | CLAUDE.md | 2 UI tasks failed QA for missing states |
```

#### Skill Improvements (→ skill files)

```markdown
### Recommended Skill Updates

| # | Skill | Update | Rationale |
|---|-------|--------|-----------|
| 1 | scorpio-execute self-QA | Add "check error handling" to self-QA prompt | Most common QA finding |
| 2 | scorpio-qa-final checklist | Add browser console check for all UI tasks | JS errors missed in 2 tasks |
| 3 | scorpio-task-plan | Require reproduction steps for all bug tasks | Bug tasks without repro had 2x rework |
```

#### Tooling Changes

```markdown
### Recommended Tooling Changes

| # | Tool | Change | Rationale |
|---|------|--------|-----------|
| 1 | ESLint | Add no-floating-promises rule | Would have caught 3 async bugs |
| 2 | Pre-commit hook | Add type-check step | 2 type errors reached QA |
```

#### Estimation Adjustments

```markdown
### Estimation Calibration

| Area | Current Accuracy | Adjustment |
|------|-----------------|------------|
| Auth module tasks | Underestimated by ~50% | Bump estimates by 1 size |
| UI component tasks | Accurate | No change |
| API endpoint tasks | Slightly under | Add buffer for error handling |
```

### Priority Matrix

```
              │ Easy to Implement │ Hard to Implement │
──────────────┼───────────────────┼───────────────────┤
High Impact   │ DO NOW            │ PLAN              │
Low Impact    │ DO IF TIME        │ SKIP              │
```

## Phase 5: Record

Persist learnings so they're available in future cycles.

### Where to Record

| Learning Type | Where to Record |
|---------------|----------------|
| Coding conventions | `CLAUDE.md` or project convention docs |
| Process changes | Skill files (update the relevant skill) |
| Project-specific patterns | `docs/PROJECT-CONTEXT.md` (add a "Lessons Learned" section) |
| Estimation calibration | `docs/ESTIMATION-GUIDE.md` (create if doesn't exist) |
| Full retrospective report | `docs/retros/RETRO-[date].md` |

### Retrospective Report Format

```markdown
# Retrospective: [Feature/Sprint Name]

**Date**: [date]
**Scope**: [what was completed]
**Participants**: [human + agent roles]

## Cycle Summary
- Tasks completed: [N]
- QA pass rate (first attempt): [N]%
- Rework cycles: [N]
- Total findings: [N]

## Key Metrics
[Gathered data from Phase 1]

## Patterns Identified
[Analysis from Phase 2]

## Insights
[Extracted insights from Phase 3]

## Recommendations

### Implemented Now
- [Changes made during this retrospective]

### Planned
- [Changes to implement before next cycle]

### Deferred
- [Changes noted but not yet prioritized]

## What Went Well
- [Positive patterns to continue]

## What to Improve
- [Patterns to address]

## Action Items
| # | Action | Owner | Status |
|---|--------|-------|--------|
| 1 | [action] | [who] | Pending |
| 2 | [action] | [who] | Pending |
```

### Updating CLAUDE.md

When adding conventions from retrospective findings:

```markdown
## Conventions (from retrospective [date])

### API Endpoints
- All endpoints must validate request body before processing
- Error responses must include a user-friendly message field
- [rationale: 4 QA findings in [feature] cycle]

### UI Components
- All async operations must have loading and error states
- [rationale: 2 QA findings in [feature] cycle]
```

Always include the rationale so future developers (and agents) understand *why* the convention exists.

## Lightweight Retro Mode

For small cycles or single-task completions, use a condensed format:

```markdown
# Quick Retro: [Task/Feature]

**What went well**: [1-2 bullets]
**What to improve**: [1-2 bullets]
**Action items**: [0-2 specific changes]
```

## What NOT To Do

- Do not run a retrospective mid-cycle (wait until tasks are complete)
- Do not blame or criticize — focus on patterns and systems
- Do not generate vague recommendations ("be more careful")
- Do not skip recording — unrecorded learnings are lost
- Do not recommend changes without evidence from the data
- Do not change skill files without noting the retrospective that prompted it
- Do not overwhelm with 20 recommendations — pick the top 3-5 highest impact

## Skill Chain

This skill closes the learning loop after release:

```
[planning] → scorpio-execute → scorpio-qa-final → scorpio-qa-rework → scorpio-release → [ship]
                                                                              │
                                                                              ▼
                                                                        retrospective
                                                                              │
                                                              ┌───────────────┼────────────────┐
                                                              ▼               ▼                ▼
                                                         CLAUDE.md      skill updates    PROJECT-CONTEXT.md
                                                        (conventions)  (process tweaks)  (lessons learned)
```

The outputs of retrospective feed forward into the *next* cycle, making planning more accurate, development more convention-compliant, and QA more targeted.