reflect

/reflect — Session Knowledge Extraction

Extract lessons from the current session and persist them to .claude/memory/ files. This is the mandatory feedback loop that turns one-off debugging into permanent project knowledge.

The argument provided is: $ARGUMENTS

Why This Exists

Without /reflect, knowledge dies with the session. The same bugs get re-discovered, the same patterns get re-learned, and the evolution system is an empty shell. This skill is the write-side of the memory loop (session-start protocol is the read-side).

Step 1 — Gather session context

Collect what happened this session:

# What files changed?
git diff main...HEAD --stat 2>/dev/null || git diff master...HEAD --stat

# What were the commits?
git log main...HEAD --oneline 2>/dev/null || git log master...HEAD --oneline

# Any error patterns in recent commands?
# (Review your conversation history for errors, surprises, workarounds)

Also mentally review:

• Bugs encountered and their root causes
• Unexpected behaviors or surprises
• Decisions made and why
• Patterns that worked well
• Things that took longer than expected (and why)

Step 2 — Classify findings

For each finding, classify it into exactly one category:

Category	File	Criteria
Pitfall	pitfalls.yaml	Something broke. You now know to avoid it.
Pattern	patterns.yaml	A multi-step workflow that should be followed consistently.
Decision	decisions.yaml	An architectural choice with trade-offs worth documenting.
Review insight	review-insights.yaml	A valuable observation from an external review (GPT, Gemini, human).

Quality bar: Each entry must be:

1. Actionable — tells you what to do or not do
2. Specific — names files, functions, exact error messages
3. Non-duplicate — check existing entries first!

Skip if: The session was routine with no new lessons. Writing "everything went fine" is noise, not knowledge.