reflection.md - a way to have claude-code self improve its context.

reflection.md

You are an expert in analyzing development sessions and optimizing AI-human collaboration. Your task is to reflect on today's work session and extract learnings that will improve future interactions.

Session Analysis Phase

Review the entire conversation history and identify:

1. Problems & Solutions

• What problems did we encounter?
  • Initial symptoms reported by user
  • Root causes discovered
  • Solutions implemented
  • Key insights learned

2. Code Patterns & Architecture

• What patterns emerged?
  • Design decisions made
  • Architecture choices
  • Code relationships discovered
  • Integration points identified

3. User Preferences & Workflow

• How does the user prefer to work?
  • Communication style
  • Decision-making patterns
  • Quality standards
  • Workflow preferences
  • Direct quotes that reveal preferences

4. System Understanding

• What did we learn about the system?
  • Component interactions
  • Critical paths and dependencies
  • Failure modes and recovery
  • Performance considerations

5. Knowledge Gaps & Improvements

• Where can we improve?
  • Misunderstandings that occurred
  • Information that was missing
  • Better approaches discovered
  • Future considerations

Reflection Output Phase

Structure your reflection in this format:

<session_overview>

• Date: [Today's date]
• Primary objectives: [What we set out to do]
• Outcome: [What was accomplished]
• Time invested: [Approximate duration] </session_overview>

<problems_solved> [For each major problem:] Problem: [Name]

• User Experience: [What the user saw/experienced]
• Technical Cause: [Why it happened]
• Solution Applied: [What we did]
• Key Learning: [Important insight for future]
• Related Files: [Key files involved] </problems_solved>

<patterns_established> [For each pattern:]

• Pattern: [Name and description]
• Example: [Specific code/command]
• When to Apply: [Circumstances]
• Why It Matters: [Impact on system] </patterns_established>

<user_preferences> [For each preference discovered:]

• Preference: [What user prefers]
• Evidence: "[Direct quote from user]"
• How to Apply: [Specific implementation]
• Priority: [High/Medium/Low] </user_preferences>

<system_relationships> [For each relationship:]

• Component A → Component B: [Interaction description]
• Trigger: [What causes interaction]
• Effect: [What happens]
• Monitoring: [How to observe it] </system_relationships>

<knowledge_updates>

Updates for CLAUDE.md

[Key points that should be added to project memory:]

• [Point 1]
• [Point 2]

Code Comments Needed

[Where comments would help future understanding:]

• File: [Path] - Explain: [What needs clarification]

Documentation Improvements

[What should be added to README or docs:]

• Topic: [What to document]
• Location: [Where to add it] </knowledge_updates>

<commands_and_tools>

Useful Commands Discovered

• [command]: [What it does and when to use it]

Key File Locations

• [Path]: [What it contains and why it matters]

Debugging Workflows

• When [X] happens: [Step-by-step approach] </commands_and_tools>

<future_improvements>

For Next Session

• Remember to: [Important points]
• Watch out for: [Potential issues]
• Consider: [Alternative approaches]

Suggested Enhancements

• Tool/Command: [What could be improved]
• Workflow: [How to optimize]
• Documentation: [What's missing] </future_improvements>

<collaboration_insights>

Working Better Together

• Communication: [What worked well]
• Efficiency: [How to save time]
• Understanding: [How to clarify requirements]
• Trust: [Where autonomy is appropriate] </collaboration_insights>

Action Items

[What should be done after this reflection:]

1. Update CLAUDE.md with: [Specific sections]
2. Add comments to: [Specific files]
3. Create documentation for: [Specific topics]
4. Test: [What needs verification]

Remember: The goal is to build cumulative knowledge that makes each session more effective than the last. Focus on patterns, preferences, and system understanding that will apply to future work.

Forked from @a-c-m’s original. This version is optimized to make sure reflections don’t get lost in the chat, but are stored and used to actually improve future collaboration with Claude.