Retro

Review artifacts and record lessons learned.

When to Use

• •After completing a feature or significant chunk of work
• •When wanting to capture insights before they fade
• •Periodic reflection on project progress

Process

1. •Review relevant .lore/ artifacts:
   • •Original spec in .lore/specs/
   • •Plan in .lore/plans/
2. •Reflect on what happened vs. what was expected
3. •Capture lessons learned
4. •Save to .lore/retros/
5. •Graduate lessons (see Lessons Graduation below)

Output

Save to .lore/retros/[feature-name].md

Document Structure

Before writing: Load ${CLAUDE_PLUGIN_ROOT}/shared/frontmatter-schema.md to get frontmatter field definitions and status values for retros.

---
[frontmatter per schema]
---

# Retro: [Feature Name]

## Summary
Brief description of what was built.

## What Went Well
- Thing 1
- Thing 2

## What Could Improve
- Thing 1
- Thing 2

## Lessons Learned
Insights to carry forward:
- Lesson 1
- Lesson 2

## Artifacts
Links to related `.lore/` documents.

Frontmatter Tips for Retros

• •title: Focus on the key lesson, not just the feature name (e.g., "N+1 query fix in brief generation" not just "Brief generation retro")
• •tags: Include problem types (bug, performance, refactor), technologies, and patterns
• •modules: Include codebase areas touched; omit if purely process/methodology focused

Lessons Graduation

After saving the retro, graduate lessons to higher scopes.

Detection

If /retro is invoked on an existing retro document (path to .lore/retros/*.md), skip the normal retro flow and run graduation only.

Flow

1. •Extract lessons from the "Lessons Learned" section
2. •If no lessons, skip graduation
3. •For each lesson, use AskUserQuestion:
   • •Prompt: Review lesson: "[lesson text]"
   • •Options:
     • •Invalid - Remove from retro
     • •Valid (Recommended) - Keep in retro only
     • •Critical - Add to project CLAUDE.md
     • •Universal - Add to ~/.claude/rules/lessons-learned.md
4. •Process classifications:
   • •Invalid: Remove lesson from retro document
   • •Valid: No action (already in retro)
   • •Critical: Append to project CLAUDE.md under "## Critical Lessons"
   • •Universal: Append to ~/.claude/rules/lessons-learned.md under inferred category

File Operations

For Critical lessons (project CLAUDE.md):

• •If "## Critical Lessons" section doesn't exist, create it at file bottom
• •Append lesson as bullet: - [lesson text]
• •Don't duplicate existing lessons

For Universal lessons (~/.claude/rules/lessons-learned.md):

• •Create file if missing with header: # Lessons Learned\n\nHard-won lessons that apply across all projects.
• •Infer category from retro tags (see Category Inference)
• •Create category section if missing
• •Append lesson as bullet under category
• •Don't duplicate existing lessons

Category Inference

Infer category from retro tags, not exact match:

Category hygiene:

• •Review existing categories before creating new ones
• •Don't let any category sprawl (10+ items suggests splitting)
• •Err on fitting into existing categories over creating new ones

Purpose

This builds organizational memory. Future work benefits from past experience - but only if it's written down.

Specialized Agents

If .lore/lore-agents.md exists, consult it for specialized agents that can help identify patterns. Reviewers can spot recurring issues or opportunities worth capturing. Invoke relevant agents via Task tool and incorporate their insights.