retro

Retrospective Review System

You are the retro reviewer for this project. Retro entries capture observations from development sessions — patterns, friction points, automation opportunities, and principle suggestions.

Retro File Format

Each retro is a markdown file in .claude/retros/ with this structure:

---
date: YYYY-MM-DD
status: open | applied | dismissed
category: skill-candidate | principle | workflow | observation | automation
severity: low | medium | high
---

## Observation
What was observed — the pattern, friction, or insight.

## Context
Why this matters. What session or task triggered it.

## Suggested Action
Concrete next step: create a skill, add a CLAUDE.md rule, add a hook, change a workflow, etc.

Commands

/retro or /retro review — Review all open retros

1. Read all .md files in .claude/retros/ (skip dotfiles)
2. Parse frontmatter to get status, category, severity
3. Filter to status: open entries
4. Group by category and present a summary table:

Categories:

Category	What it means	Typical action
skill-candidate	A repetitive task pattern that deserves a /skill	Create a new skill in .claude/skills/
principle	A development principle that should be enforced	Add to CLAUDE.md or create a hook
workflow	A workflow improvement or process change	Update settings, hooks, or CLAUDE.md
observation	A noteworthy pattern worth tracking	Keep open or convert to another category
automation	Something that should be automated via hook/script	Create a hook in .claude/hooks/

5. For each open retro, suggest a concrete action and ask the user which ones to apply

/retro create <slug> — Create a new retro entry

Create a new retro file at .claude/retros/YYYY-MM-DD-<slug>.md with the standard format. Ask the user for the observation, context, and suggested action.

/retro apply <slug> — Apply a retro's suggested action

1. Read the retro file at .claude/retros/*<slug>*.md
2. Show the user what the suggested action will change (files to create/edit) and get confirmation
3. Execute the action (create skill, update CLAUDE.md, create hook, etc.)
4. After successful execution, update the retro file's frontmatter status: open to status: applied using the Edit tool
5. Append an ## Applied section to the retro with the date and a brief summary of what was done

/retro dismiss <slug> — Dismiss a retro

1. Ask the user for a brief reason
2. Update the retro file's frontmatter status: open to status: dismissed using the Edit tool
3. Append an ## Dismissed section with the date and reason

Review Presentation

When reviewing, present retros grouped by category with severity indicators:

## Open Retros (N total)

### Skill Candidates (N)
- [HIGH] 2026-04-09-repeated-docker-rebuild — We keep manually rebuilding Docker after changes
  -> Suggest: Create /rebuild skill with smart service detection

### Principles (N)
- [MED] 2026-04-08-test-before-code — Multiple instances of writing code first, tests after
  -> Suggest: Add "Write tests first" enforcement to CLAUDE.md

### Workflow (N)
- [LOW] 2026-04-07-api-token-refresh — Token refresh is manual and error-prone
  -> Suggest: Add a hook that auto-refreshes expired tokens

Then ask: "Which retros would you like to apply? (Enter numbers, 'all', or 'skip')"

When the user selects retros to apply:

1. For each selected retro, run the /retro apply flow (show plan, confirm, execute, update status)
2. For retros the user explicitly rejects, ask if they want to dismiss them

When the user says "skip", leave all retros as status: open for next time.

Important

• Never delete retro files — only change their status
• When applying a retro, show the user exactly what will change before doing it
• Retros are project-specific — they live in the git repo and are shared with collaborators
• When creating skills from retros, follow the skill format in .claude/skills/