---
name: reflect
description: >
  Run a milestone reflection after completing a milestone. Reviews the full conversation history,
  git log, and current project docs to produce structured reflection artifacts. Use when a milestone
  is complete and verified. Invoke with the milestone number, e.g. /reflect M8
allowed-tools: Read, Edit, Write, Grep, Glob, Bash(git *)
---

# Milestone Reflection Skill

You are performing a milestone reflection for milestone **$ARGUMENTS**.

## Context

You have access to the full conversation history in your context window. Your job is to
review **everything** that happened during this milestone — every commit, every debugging
detour, every wrong assumption, every backtrack — and distill it into structured artifacts.

## Pre-gathered context

### Git log for this milestone
!`git log --oneline --since="$(git log --all --oneline --grep="[Mm]$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1-1}').*[Vv]erif\|[Mm]$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1-1}').*[Rr]eflect\|[Mm]$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1-1}').*[Cc]omplete" --format='%aI' | head -1 || echo '3 months ago')" 2>/dev/null || git log --oneline -30`

### Current MEMORY.md
!`cat MEMORY.md 2>/dev/null || echo "No MEMORY.md found"`

### Current FUTURE.md
!`cat FUTURE.md 2>/dev/null || echo "No FUTURE.md found"`

### Current README.md (scripts section)
!`sed -n '/## Scripts/,/^## /p' README.md 2>/dev/null | head -60 || echo "No Scripts section found"`

### Available scripts
!`ls -1 scripts/ 2>/dev/null || echo "No scripts directory"`

### Verify script for this milestone
!`cat scripts/verify-m$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1}').sh 2>/dev/null || echo "No verify script found for this milestone"`

## Instructions

Review the **entire conversation** from the start of this milestone. Do NOT just look at the
final state — examine the journey: wrong turns, debugging sessions, repeated commands, surprises.

### Step 1: Draft the reflection

Before editing any files, write out your reflection analysis covering these four areas:

1. **Process improvements:** What slowed us down? Wrong assumptions? Circles or backtracks?
   What could be automated? What would make this faster if redone from scratch?

2. **Key knowledge for reproduction:** Critical facts, gotchas, version quirks, network
   constraints, configuration details that caused debugging detours. Things a future session
   needs to know.

3. **Scripts and automation:** Commands run repeatedly that should be scripts. Existing scripts
   that proved valuable. Multi-step manual processes to condense.

4. **Future improvements:** Ideas that surfaced but don't belong in current scope. These go
   in FUTURE.md with Problem/Idea/Open questions/Depends on format.

### Step 2: Count the commits

Analyze the git log to quantify:
- Total commits for this milestone
- How many were fixes vs. forward progress
- Number of pushes / syncs if identifiable
- Longest debugging detour

### Step 3: Update files

Update these files in order:

1. **MEMORY.md** — Add a `## $ARGUMENTS Reflection — <title>` section with the reflection
   bullets. Also update any existing sections (Gotchas, Process Lessons, Key Patterns) with
   new learnings from this milestone.

2. **FUTURE.md** — Add any new future improvement ideas in the standard format.

3. **README.md** — Update the milestone table status and the Scripts section with any new scripts.

4. **CLAUDE.md** — Update the repo structure if it changed, and add any new conventions or
   patterns discovered.

### Step 4: Summary

After all edits, provide a brief summary:
- Number of new gotchas added
- Number of new FUTURE items
- Key theme of the milestone (1 sentence)
- Biggest process lesson (1 sentence)

## Quality checks

- Every bullet in the reflection should be **actionable or informative** — no filler
- Gotchas should include the **symptom AND the fix**, not just "X was tricky"
- Process lessons should be phrased as **rules** ("Always X before Y", "Never assume Z")
- Future items need all four fields (Problem/Idea/Open questions/Depends on)
- Use the same formatting style as existing reflections in MEMORY.md