/retrospecting

Session Analytics Context

Data Sources for Session Analysis

1. Git History Analysis

What to Examine:

• Commits made during the session (timestamps, messages, changed files)
• Diffs showing actual code changes and their scope
• Branch activity and merge patterns
• File modification frequency and complexity

Key Metrics:

• Number of files modified/created/deleted
• Lines of code added/removed
• Commit frequency and granularity
• Commit message quality and clarity

Commands for Analysis:

# Get commits from session time range
git log --since="YYYY-MM-DD HH:MM" --until="YYYY-MM-DD HH:MM" --oneline

# Detailed diff for session
git diff <start-commit>...<end-commit> --stat

# Files changed during session
git diff <start-commit>...<end-commit> --name-only

2. Claude Logs Analysis

What to Examine:

• ~/.claude/projects/{project-dir}/{session-id}.jsonl - Claude Code native session logs (JSONL format)
  • Project directory is calculated by transforming absolute working directory: $(echo "${PWD}" | sed 's/\//\-/g')
  • Example: /Users/user/project becomes ~/.claude/projects/-Users-user-project/
• Tool usage patterns (which tools were called, frequency, success rates)
• Error messages and retry patterns
• Decision-making rationale in responses

Key Indicators:

• Repeated tool calls suggesting exploration or confusion
• Error recovery patterns
• Context switches and task transitions
• Clarification requests and user interactions

3. Project Files Analysis

What to Examine:

• Test coverage changes (new tests added, coverage percentages)
• Code quality indicators (complexity, duplication, adherence to standards)
• Documentation updates (README, inline comments, API docs)
• Build and compilation status

Key Metrics:

• Test-to-production code ratio
• Compilation success/failure
• Adherence to project coding standards
• Documentation completeness

4. User Feedback

What to Gather:

• Session goals and whether they were achieved
• User satisfaction with outcomes
• Pain points or friction during the session
• Specific examples of what worked well or poorly

Gathering Methods:

• Direct prompting: "What were your goals for this session?"
• Targeted questions: "Which parts of this session were most/least effective?"
• Outcome validation: "Did the implementation meet your expectations?"

5. Sub-agent Interaction Analysis

What to Examine (when applicable):

• Which sub-agents were invoked during the session
• Task handoffs between Claude and sub-agents
• Sub-agent success rates and output quality
• Communication clarity in agent instructions

Feedback Collection:

• Invoke sub-agents with retrospective prompts
• Ask about instruction clarity, tool availability, context sufficiency
• Gather suggestions for improved coordination

Analysis Framework

Success Indicators

Code Quality:

• Compilation succeeds without errors
• Tests pass with appropriate coverage
• Code follows project standards and patterns
• Security considerations properly addressed

Workflow Efficiency:

• Minimal rework or backtracking
• Efficient tool usage (right tool for the task)
• Clear progression toward stated goals
• Effective user-Claude communication

Learning & Adaptation:

• Applying lessons from earlier in session
• Recognizing and correcting mistakes
• Adapting approach based on feedback
• Discovering and using existing patterns

Problem Indicators

Code Quality Issues:

• Compilation failures or test failures
• Deviations from project architecture/style
• Security vulnerabilities introduced
• Missing or inadequate documentation

Workflow Inefficiencies:

• Repeated failed attempts at same task
• Excessive tool calls without progress
• Misunderstanding requirements (multiple clarifications)
• Creating new patterns when existing ones should be used

Communication Gaps:

• Ambiguous instructions leading to wrong implementations
• User frustration or confusion
• Missing context causing incorrect assumptions
• Inadequate status updates or progress visibility

Quantitative Metrics to Track

Session Scope Metrics

• Duration: Total time from session start to completion
• Task Count: Number of distinct tasks/subtasks completed
• File Impact: Files created, modified, deleted
• Code Volume: Lines added, removed, net change

Quality Metrics

• Compilation Rate: % of time code compiled successfully
• Test Coverage: Coverage percentage change during session
• Rework Rate: % of changes that required revision
• Standard Compliance: Adherence to project coding standards

Efficiency Metrics

• Tool Success Rate: % of tool calls that succeeded on first attempt
• Context Switches: Number of major topic/task transitions
• Clarification Rate: User questions per task completed
• Completion Rate: % of stated goals fully achieved

User Experience Metrics

• Satisfaction: User-reported satisfaction (if gathered)
• Friction Points: Number of reported pain points
• Value Delivered: User assessment of outcome usefulness
• Would Repeat: User willingness to use approach again

Qualitative Analysis Areas

Pattern Recognition

• Successful Approaches: What techniques led to good outcomes?
• Problematic Patterns: What approaches caused issues?
• Reusable Solutions: What can be extracted for future use?
• Context-Specific Learnings: What only applies to this project/task type?

Communication Effectiveness

• Instruction Clarity: Were instructions clear and actionable?
• Context Sufficiency: Was enough context provided upfront?
• Feedback Loops: How well did iterative feedback work?
• User Engagement: Appropriate level of user involvement?

Technical Excellence

• Architecture Alignment: Proper use of established patterns?
• Code Quality: Maintainable, readable, well-structured code?
• Testing Rigor: Appropriate test coverage and quality?
• Security Awareness: Proper handling of security considerations?

Retrospective Output Guidelines

Structure Recommendations

1. Executive Summary: High-level overview of session outcomes
2. Quantitative Metrics: Data-driven assessment of performance
3. Qualitative Insights: Pattern analysis and learnings
4. Action Items: Specific, prioritized improvements for future sessions

Actionability Standards

• Every recommendation should be specific (not vague)
• Include evidence from session data to support claims
• Provide implementation guidance for improvements
• Prioritize based on impact and feasibility

Audience Considerations

• Users: Want to know if goals were met, what to improve
• Future Claude sessions: Need actionable patterns to replicate or avoid
• Marketplace consumers: Need to understand value and use cases
• Plugin developers: May extend or integrate with other tools

This context provides a comprehensive framework for analyzing Claude Code sessions systematically and generating valuable retrospective insights.