custom-claude-skills/skills/reflect/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
reflect	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	Read, Edit, Write, Grep, Glob, Bash(git log *), Bash(git diff *), Bash(git show *), Bash(cat *), Bash(sed *), Bash(ls *)

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 (last 50 commits)

!git log --oneline -50

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

(Read the verify script manually using the Read tool: scripts/verify-m<N>.sh where N is the milestone number from $ARGUMENTS)

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. If the project follows the thin-index pattern (a claude/ directory with per-topic detail files referenced from CLAUDE.md), per-subsystem conventions belong in the appropriate claude/<topic>.md file. Only edit the root CLAUDE.md for always-applies guardrails, the architecture overview, or the pointer table itself.

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