Skip to main content

Use /reflect

handbook-extras

Create reflective analyses of your Claude Code sessions to improve your development workflow and capture lessons learned.

The /reflect command helps you step back and analyze the meta aspects of your work session - not what you built, but how you built it. It generates a structured markdown reflection covering techniques used, what worked well, lessons learned, and actionable improvements for future sessions.

When to Use​

Use /reflect to:

  • After completing a significant task: Capture insights while they're fresh
  • When encountering repeated challenges: Document patterns to avoid in the future
  • For team knowledge sharing: Create reusable workflow improvements
  • During skill development: Track your growth in using Claude Code effectively

Command Specification​

---
description: Create a reflective analysis of the current Claude Code session, focusing on techniques, patterns, lessons learned, and workflow improvements.
---

# Session Reflection

Create a reflective analysis of this Claude Code session.

## Purpose

This reflection focuses on **META aspects** of the session - not what was implemented/fixed, but HOW the work was done:
- Techniques and approaches used
- What worked well vs. what didn't
- Lessons learned for future sessions
- Actionable improvements

## Instructions

1. **Analyze the Current Session**

   Review the conversation history and identify:
   - Problem-solving approaches used
   - Tool usage patterns (which tools, how effectively)
   - Communication patterns (clarifications, iterations)
   - Planning and execution strategies
   - Any blockers, pivots, or course corrections

2. **Generate the Reflection**

   Create a markdown file at: `.claude/reflections/<date>-<name>.md`

   Where:
   - `<date>` is today's date in `YYYY-MM-DD` format
   - `<name>` is a short kebab-case slug (2-4 words) derived from the **gist** of the conversation (e.g., `api-debugging`, `test-refactoring`, `feature-planning`)

   Ensure the `.claude/reflections/` directory exists before writing.

3. **Use This Structure**

```markdown
# Session Reflection: [Brief Title]

**Date**: YYYY-MM-DD
**Session Goal**: [One-line summary of what the session aimed to accomplish]

---

## What Went Well

- [Effective technique or approach]
- [Tool usage that was particularly helpful]
- [Communication pattern that worked]

## What Went Wrong

- [Approach that didn't work or caused delays]
- [Tool misuse or inefficiency]
- [Unnecessary iteration or backtracking]

## Lessons Learned

1. **[Lesson Title]**: [Explanation of the insight and why it matters]
2. **[Lesson Title]**: [Explanation of the insight and why it matters]

## Action Items

- [ ] [Specific improvement to apply in future sessions]
- [ ] [Process or workflow change to consider]

## Tips & Tricks for Claude Code

Based on this session, useful patterns for future reference:

- **Tip**: [Specific Claude Code tip discovered or reinforced]
- **Tip**: [Another useful pattern or shortcut]

## Generalization Opportunities

Consider creating reusable artifacts if this session revealed repeatable patterns. For example:

- **Slash Command**: [If a specific workflow could be automated]
- **Agent**: [If a specialized task could be delegated]
- **Skill**: [If a multi-step process with assets would help]

[Only include this section if genuinely applicable. Before generalizing, ensure the pattern is genuinely reusable across multiple contexts. Premature abstraction can add complexity without benefit.]

---

*Generated by `/reflect` command*
```

## Guidelines

- **Be honest and specific** - vague observations aren't actionable
- **Focus on process, not outcomes** - "we used X approach" not "we built Y feature"
- **Prioritize actionable insights** - each lesson should inform future behavior
- **Keep it concise** - quality over quantity
- **Skip sections if not applicable** - empty sections add no value

Output​

The command creates a markdown file at .claude/reflections/<date>-<name>.md with structured sections including:

  • What Went Well: Effective techniques and approaches
  • What Went Wrong: Areas for improvement
  • Lessons Learned: Key insights from the session
  • Action Items: Specific improvements to apply next time
  • Tips & Tricks: Claude Code patterns discovered
  • Generalization Opportunities: Potential for reusable components

Benefits​

  • Continuous improvement: Build better workflows over time
  • Team learning: Share effective patterns across your team
  • Pattern recognition: Identify what works and what doesn't
  • Skill development: Accelerate mastery of Claude Code
  • Documentation: Create a searchable knowledge base of sessions

Example Usage​

After debugging a complex API integration:

/reflect

This might generate: .claude/reflections/2025-01-25-api-debugging.md documenting your problem-solving approach, tool usage patterns, and lessons learned about API troubleshooting with Claude Code.

  • /explain - Get detailed explanations of code and concepts
  • /five-whys - Perform root cause analysis on problems