85dfa2ef2e
The !`command` blocks in SKILL.md go through Claude Code's Bash permission checker, which rejects $() command substitution. Simplified the git log command, replaced dynamic verify script path with a Read tool instruction, and narrowed allowed-tools to specific command patterns. Also documented the constraints in CLAUDE.md for future skill development. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
---
|
|
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 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.
|
|
|
|
### 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
|