teamcraft:run-retro

---
name: teamcraft:run-retro
description: Run a retrospective — AI compiles evidence from recent work, facilitates human reflection, and captures process decisions back into living docs. Use when the user says 'run a retro', 'let's do a retrospective', 'run a retrospective on the last 2 weeks', 'let's reflect on how that feature went', or 'time for a retro'.
argument-hint: "[time period or scope, e.g. 'last 2 weeks', 'the notification feature', or empty for default]"
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
---

## Goal

Facilitate a useful retrospective by compiling evidence from the repo, surfacing patterns the developer might not have noticed, and helping them decide what to change. The retro report is saved to `.teamcraft/retros/`, but the real output is process decisions that feed back into living documents (`.claude/rules/`, `/docs/decisions/`).

## Gather Evidence

**1. Understand the scope.** `$ARGUMENTS` is a time period, a feature name, or empty. If empty, default to the last 2 weeks. Ask the developer to confirm the scope.

**2. Read what's available.** Gather evidence from whatever exists — don't fail if some sources are missing:

- **Work items:** Read `.teamcraft/work/INDEX.md` and any work items completed in the period. Look at `created`, `started`, and `completed` dates to compute cycle times.
- **Git history:** `git log` for the period. What was committed, how many commits, any patterns in commit frequency or size.
- **Work item status changes:** `git log --follow` on work item files to see status transitions and timing.
- **PR history:** If accessible, check PR merge times, review cycles.

If none of this structured data exists (no work items, new to Teamcraft), fall back to git history alone and ask the developer to fill in context.

**3. Compile findings.** Surface patterns, not just facts:

- **Cycle time:** How long did work items take from started to completed? Any outliers?
- **What took longer than expected?** Compare effort estimates (if set) to actual cycle time. What explains the gap?
- **Patterns in the work:** Were there recurring themes (lots of bug fixes? infrastructure chores? one big feature)?
- **Test/CI patterns:** Any repeated CI failures? Test coverage changes?
- **Anything surprising:** Commits at unusual times, work items that were created and completed the same day, abandoned branches.

## Facilitate the Conversation

Present your findings to the developer. Then facilitate — don't drive. The retrospective is the developer's reflection, not your report.

Ask:
- "What went well that we should keep doing?"
- "What was frustrating or took longer than it should have?"
- "Is there anything you want to change about how we work?"

Listen to the developer's answers. Connect their observations to the evidence you found when relevant. If they identify something to change, help them articulate it as a concrete decision.

## Capture Decisions

This is the most important part. Process improvements that don't get written down don't happen.

For each decision the developer makes, route it through the skill that owns that knowledge domain:

- Operating convention change (branching, testing, review, merge, deploy, etc.) → `/capture-team-conventions` handles updating the conventions document and any gotcha promotions
- Architecture or technology decision change → `/capture-technical-design` handles updating the architecture or per-area decision file and any gotcha promotions
- Requirement change → `/capture-requirements` handles updating the PRD and any gotcha promotions
- A newly-discovered gotcha with no other category implication → `/capture-team-conventions` handles the promotion (gotchas live under conventions by default)

This skill surfaces decisions; the capture skills are the authoritative writers for their respective knowledge categories. Do not write directly to conventions, architecture, decisions, PRDs, `CLAUDE.md`, or `.claude/rules/` from here — single-skill domain ownership applies.

Present each decision to the developer, confirm, then invoke the relevant capture skill when the developer is ready. The developer may choose to batch multiple decisions into one capture session or handle them separately.

## Save the Retro Report

Write a summary to `.teamcraft/retros/YYYY-MM-DD.md`. Include:
- The scope (time period or feature)
- Key findings (evidence-based)
- What went well
- What to improve
- Decisions made (with pointers to where they were captured)

If `.teamcraft/retros/` doesn't exist, create it.

Commit the retro report and any updated docs/rules.

## Constraints

- The developer's observations take priority over your analysis. If they say something went well and your metrics suggest otherwise, surface the discrepancy but don't argue.
- Not every retro produces process changes. Sometimes things are going well. That's a valid outcome.
- Don't suggest changes to the codebase. This is about process, not code.