reflect

name

reflect

description

Capture durable lessons from a session before they fade. What surprised you, what friction repeated, what should update CLAUDE.md or notes, what insight would help future-you. Use at session end after work has shipped or reached a natural pause. Triggers on /reflect, "what did we learn", "lessons learned", "session retro", "what should we save", "should we update CLAUDE.md". Also invoke proactively at the end of substantive work or at a natural session pause, while the friction and surprises are still in context.

/reflect: capture lessons before they fade

A session ended. The work shipped, or hit a natural pause. The friction, surprises, and insights are still warm in context, but they decay fast. The next session won't remember what surprised you today.

This skill is the discipline of capturing what's worth keeping before the context evaporates. The output is durable artifacts: memory entries, note updates, CLAUDE.md changes, whatever will help future-you avoid repeating the friction or recreating the insight.

What to surface

Five questions to scan. Ask only those that have real signal:

• What surprised me? Moments where reality didn't match the prior. Usually the highest-signal lessons.
• What friction repeated? Pain that happened more than once this session. Single occurrences are noise; repeats are signal.
• What CLAUDE.md update would have prevented something today? A rule or instruction missing from your global setup.
• What pattern emerged that's worth naming? A recurring shape, idiom, or approach that worked. Naming makes it reusable.
• What's worth saving as a durable note? Knowledge that will be useful in future sessions but doesn't fit anywhere yet.

If a question has no signal, skip it. Reflection isn't a checklist to fill. It's a salvage operation.

Where to write

Match the artifact to the type of insight:

• CLAUDE.md updates: for behaviors that should change globally (rules, defaults, anti-patterns).
• Project notes: for durable knowledge specific to a project or domain.
• Memory entries: for facts about the user, project state, or relationships that need to persist.
• Daily memory: for session-specific context that might be useful soon.
• Tooling tickets: for friction that needs a code or process change, not just a note.

How to write the artifact

• Lead with the actionable lesson, not the story. "Verify before declaring done" beats "Today I declared done and the bug surfaced an hour later..." A vague "be more careful with X" doesn't survive contact with the next session; concrete rules do.
• Cite the trigger if useful. Brief context about when the lesson applies, not the full narrative.
• Cap the length. A reflection note longer than a paragraph won't get re-read.

After reflecting

Surface the captured insights briefly: "Saved: [list]." Then proceed to next steps (or end the session). Don't re-debate the captures. They're cheap to revise later.

Common pitfalls

Reflection is the most-skipped phase because it has no immediate payoff. Watch for:

• "It's obvious now" drift. Assuming the lesson doesn't need to be written because you'll remember. You won't. "Saving without writing" is not reflection. If it's not in a file, it didn't happen.
• Skipping because nothing felt remarkable. The absence of remarkable moments is itself information. Note it.
• Padding to look thorough. Manufacturing lessons because the skill expects output. If nothing surfaced, say so.
• Story-shaped lessons. Narrative without distillation. Catalog without curation. Future-you wants the rule, not the anecdote.
• Saving in the wrong place. Durable knowledge in daily memory, ephemeral in CLAUDE.md. Match persistence to artifact.