Retrospecting

Session Retrospective Skill

Auto-Loaded Context

Session Analytics: `contexts/session-analytics.md` - Provides comprehensive framework for analyzing sessions, including data sources, metrics, and analysis methods.

Retrospective Templates: `templates/retrospective-templates.md` - Standardized report templates for different retrospective depths.

Core Responsibilities

1. Multi-Source Data Collection

Systematically gather data from all available sources:

• Git History: Commits, diffs, file changes during session timeframe
• Claude Logs: Conversation transcripts, tool usage, decision patterns
• Project Files: Test coverage, code quality, compilation status
• User Feedback: Direct input about goals, satisfaction, pain points
• Sub-agent Interactions: When sub-agents were used, gather their feedback

2. Quantitative Analysis

Calculate measurable metrics:

• Session scope (duration, tasks completed, files changed)
• Quality indicators (compilation rate, test coverage, standard compliance)
• Efficiency metrics (tool success rate, rework rate, completion rate)
• User experience data (satisfaction, friction points)

3. Qualitative Assessment

Identify patterns and insights:

• Successful approaches that led to good outcomes
• Problematic patterns that caused issues or delays
• Reusable solutions worth extracting for future use
• Context-specific learnings applicable to this project type

4. Report Generation

Create structured retrospective report using appropriate template:

• Quick Retrospective: Brief session wrap-ups (5-10 minutes)
• Comprehensive Retrospective: Detailed analysis for significant sessions
• Choose template based on session complexity and user needs

Working Process

Step 0: Quick Session Assessment

Before gathering data, determine the appropriate analysis depth:

1. Check session size:

   # Count recent commits
   git log --oneline --since="1 hour ago" | wc -l

   # List session log files with metadata
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/list-sessions.sh --sort date | head -5

2. Suggest depth to user based on metrics:

• Quick (<10 commits, <5MB logs): "5-10 min lightweight analysis"
• Standard (10-25 commits, 5-20MB logs): "15-20 min balanced analysis"
• Comprehensive (>25 commits, >20MB logs): "30+ min deep-dive analysis"

3. Let user override: "Based on [X commits, Y MB logs], I recommend a [MODE] retrospective (~Z minutes). Does this work for you, or would you prefer a different depth?"

4. Early exit clause: If user says "just a quick summary" or "high-level overview", automatically use Quick mode regardless of session size.

Step 1: Establish Session Scope

1. Ask user to define session boundaries (time range or commit range) 2. Clarify session goals: "What were you trying to accomplish?" 3. Confirm retrospective depth from Step 0

Step 2: Gather Data

Execute data collection based on confirmed depth mode:

Depth-Specific Data Collection

Quick Mode:

• Git: git diff <start>..<end> --stat only (no full diffs)
• Logs: Extract statistics and errors only via extracting-session-data skill
• Files: Check compilation status only
• User: 2-3 targeted questions
• Skip: Sub-agent feedback, detailed file analysis

Standard Mode:

• Git: Full commit history + stats, selective diffs for key files
• Logs: Extract metadata, statistics, tool-usage, and errors via extracting-session-data skill
• Files: Quality metrics for changed files
• User: 5-7 questions covering main areas
• Include: Sub-agent feedback if applicable

Comprehensive Mode:

• Git: Everything (full logs, diffs, file analysis)
• Logs: Extract all data types via extracting-session-data skill, may read full logs if <500 lines
• Files: Deep analysis including tests, architecture compliance
• User: Extensive feedback (8-10 questions)
• Include: All sub-agent feedback, pattern extraction

Git Analysis

Use the analyzing-git-sessions skill to collect git data:

Quick Mode: Request "concise" output (stats only, no diffs) Standard Mode: Request "detailed" output for key files Comprehensive Mode: Request "code review" format for full analysis

Invoke skill with session timeframe:

Skill: analyzing-git-sessions
Input: "<start-time> to <end-time>" or "<start-commit>..<end-commit>"
Depth: [concise|detailed|code-review] based on retrospective mode

The skill will return structured git metrics needed for retrospective analysis.

Log Processing (Size-Aware)

Use the extracting-session-data skill to access Claude Code native session logs efficiently.

1. List Available Sessions:

   # List all sessions with metadata (size, lines, date, branch)
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/list-sessions.sh

2. Check Session Size:

   # Get statistics for specific session
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/extract-data.sh \
       --type statistics --session SESSION_ID

3. Extract Data Based on Session Size and Mode:

Quick Mode (or any session >2000 lines):

   # Extract only statistics and errors
   extract-data.sh --type statistics --session SESSION_ID
   extract-data.sh --type errors --session SESSION_ID --limit 10

Standard Mode (sessions 500-2000 lines):

   # Extract metadata, statistics, tool usage, and errors
   extract-data.sh --type metadata --session SESSION_ID
   extract-data.sh --type statistics --session SESSION_ID
   extract-data.sh --type tool-usage --session SESSION_ID
   extract-data.sh --type errors --session SESSION_ID

Comprehensive Mode (sessions <500 lines):

   # Extract all available data
   extract-data.sh --type all --session SESSION_ID

   # Or read full log file if needed for detailed analysis
   # (Only for small sessions - check line count first!)

4. Multi-Session Analysis:

   # Filter sessions by criteria
   filter-sessions.sh --since "7 days ago" --branch main

   # Extract data from all filtered sessions (omit --session flag)
   extract-data.sh --type statistics  # Runs on all sessions

5. Synthesize Extracted Data: After extraction, synthesize data into compact summary (max 200 lines) before continuing to analysis.

Path Calculation: The extracting-session-data skill handles all path calculations automatically. Session logs are stored in ~/.claude/projects/{project-identifier}/ where the identifier is derived from the working directory path.

Project Analysis

Examine changed files, tests, documentation (depth-appropriate)

User Feedback

Prompt for direct feedback on session experience (question count based on depth mode)

Sub-agent Feedback

If sub-agents were used, invoke them to gather their perspective (Standard/Comprehensive modes only)

Step 3: Analyze Data

Apply session-analytics.md framework:

• Calculate quantitative metrics
• Identify success and problem indicators
• Extract patterns (successful approaches and anti-patterns)
• Assess communication effectiveness and technical quality

Step 4: Generate Insights

Synthesize analysis into actionable insights:

• What went well and why (specific evidence)
• What caused problems and their root causes
• Opportunities for improvement (prioritized by impact)
• Patterns to replicate or avoid in future sessions

Step 5: Create Report

Use appropriate template from retrospective-templates.md:

• Structure findings clearly with evidence
• Include specific file:line references where relevant
• Prioritize recommendations by impact and feasibility
• Make all suggestions actionable and specific

Step 6: Gather User Validation

Present report and ask:

• Does this match your experience?
• Are there other pain points we missed?
• Which improvements would be most valuable to you?

Step 7: Suggest Configuration Improvements

If the retrospective identifies areas for improvement in Claude or Agent interactions:

1. Analyze whether improvements could be codified in configuration files:

• CLAUDE.md: Core directives, workflow practices, communication patterns
• SKILL.md files: Skill-specific instructions, working processes, anti-patterns
• Agent definition files: Agent prompts, tool usage, coordination patterns

2. Draft specific, actionable suggestions for configuration updates:

• Quote the current text that should be modified (if updating existing content)
• Provide the proposed new or additional text
• Explain the rationale based on retrospective findings

3. Present suggestions to the user:

• "Based on this retrospective, I've identified potential improvements to [file]. Would you like me to implement these changes?"
• Show the specific changes that would be made

4. If the user approves:

• Apply the changes using the Edit tool
• Confirm what was updated

5. If the user declines:

• Document the suggestions in the retrospective report for future consideration

Step 8: Session Archive Information

After the retrospective report is created and validated:

1. Inform the user where session logs are stored:

• "Session logs are permanently stored in ~/.claude/projects/{project-dir}/{session-id}.jsonl"
• "These logs are managed by Claude Code and should not be deleted manually"

2. Explain that retrospective reports are saved separately in:

• ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/

3. Note that Claude Code manages session log retention automatically

Output Standards

Report Quality Requirements

• Evidence-Based: Every claim backed by specific examples
• Actionable: All recommendations include implementation guidance
• Specific: Avoid vague statements; use concrete examples
• Prioritized: Clear indication of high vs low impact items
• Balanced: Acknowledge successes while identifying improvements

File References

Use file:line_number format when referencing specific code locations.

Metrics Presentation

Present metrics in clear tables or lists with context for interpretation.

Recommendations Format

Each recommendation should include:

• What: Specific action to take
• Why: Root cause or rationale
• How: Implementation approach
• Impact: Expected benefit

Integration with Sub-agents

When sub-agents were used during the session:

Feedback Collection

Invoke each sub-agent that participated with prompts like:

• "What aspects of this session worked well for you?"
• "What instructions or context were unclear?"
• "What tools or capabilities did you need but lack?"
• "How could coordination with Claude be improved?"

Synthesis

Incorporate sub-agent feedback into retrospective:

• Identify coordination issues or handoff problems
• Note gaps in instruction clarity or context
• Recognize successful collaboration patterns
• Recommend improvements to sub-agent usage

Context Budget Management

Monitor context usage throughout retrospective to prevent overflow:

Budget Thresholds

• Skill instructions: ~6-8K tokens (this file + auto-loaded contexts)
• Small log file: 2-5K tokens per file
• Large log file: 10-50K+ tokens if read fully
• Git diffs: 5-20K tokens for large changes
• User conversation: Variable (2-10K tokens)

Adaptive Strategy Based on Remaining Budget

High Budget (>100K tokens remaining):

• Safe to use Comprehensive mode
• Read full logs if <2000 lines
• Include full git diffs
• Load detailed metrics from session-analytics.md if needed

Medium Budget (50-100K tokens remaining):

• Use Standard mode by default
• Summarize logs before reading (use bash extraction)
• Selective git diffs for key files only
• Skip extended context loading

Low Budget (<50K tokens remaining):

• Force Quick mode regardless of session size
• Bash-only log summarization (no full reads)
• Git stats only, no diffs
• Warn user: "Limited context available - providing focused analysis on key areas only"

Context Preservation Tactics

1. Extract and discard: Pull key metrics from large files, discard verbose source immediately 2. Synthesize early: Create compact summaries (max 200 lines) before continuing 3. Progressive refinement: Start high-level, drill down only where user indicates interest 4. Spot sampling: Read representative sections rather than entire files

Emergency Fallback

If approaching context limit during analysis:

1. Stop data collection immediately 2. Generate report from data gathered so far 3. Note in report: "Analysis limited by context constraints - [specific areas not covered]" 4. Offer to do targeted follow-up on specific aspects in new conversation

Anti-Patterns to Avoid

Don't:

• Generate retrospectives without gathering actual data
• Make vague, non-actionable recommendations
• Focus only on negatives; acknowledge what worked well
• Ignore user's stated priorities and goals
• Create overly long reports that bury key insights
• Analyze sessions without understanding the context and goals

Do:

• Ground analysis in concrete evidence from session data
• Provide specific, actionable recommendations with implementation guidance
• Balance positive recognition with improvement opportunities
• Align recommendations with user's priorities
• Create concise reports that highlight key insights prominently
• Understand session context before analyzing effectiveness

Cross-Plugin Enrichment

When sibling Bitwarden plugins are installed, retrospectives gain specialist analysis:

Security-Aware Retrospectives (bitwarden-security-engineer plugin)

After collecting git diffs from the session:

• Scan for committed credentials → activate Skill(detecting-secrets) against the session's git diffs to warn if secrets were inadvertently committed
• Assess security posture of new code → if the session introduced auth, crypto, or input-handling code, activate Skill(analyzing-code-security) to flag potential vulnerabilities in the retrospective report

Quality Classification (bitwarden-code-review plugin)

• Classify session changes by impact → activate Skill(classifying-review-findings) to categorize the session's changes using the CRITICAL/IMPORTANT/DEBT/SUGGESTED framework, giving users a clear picture of what needs attention

These skills are optional. If unavailable, proceed with standard retrospective analysis.

Success Criteria

A good retrospective should:

1. Inform: User learns something new about their workflow 2. Guide: Clear next steps for improvement 3. Motivate: Recognition of successes encourages continued good practices 4. Focus: Prioritization helps user know where to invest effort 5. Enable: Provides frameworks/patterns user can apply to future sessions

Report Storage

Directory: ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/

Filename format: YYYY-MM-DD-session-description-SESSION_ID.md

• Use ISO date format (YYYY-MM-DD) for chronological sorting
• Keep description brief (3-5 words, hyphen-separated)
• Include session ID from log files for traceability

Example path: ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/2025-10-23-authentication-refactor-3be2bbaf.md

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.

Session Retrospective Skill

Comprehensive analysis of Claude Code sessions to identify successful patterns, problematic areas, and opportunities for improvement.

What It Does

This skill analyzes completed Claude Code sessions by examining:

• Git history (commits, diffs, file changes)
• Claude Code native session logs from ~/.claude/projects/{project-dir}/{session-id}.jsonl
• Code quality metrics (tests, compilation, standards)
• Your direct feedback about the session

It produces a structured retrospective report with:

• Quantitative metrics (files changed, test coverage, tool usage)
• Qualitative insights (what worked, what didn't, why)
• Actionable recommendations for future sessions
• Reusable patterns and anti-patterns

When to Use

Invoke this skill when you want to:

• Review what was accomplished in a session
• Understand what went well and what could improve
• Get feedback on workflow effectiveness
• Document lessons learned for future reference
• Analyze a particularly successful or challenging session

Example Invocations

Natural language:

• "Can you do a retrospective on what we just accomplished?"
• "How did that session go?"
• "Analyze the last 2 hours of work"
• "What could we improve about how we worked together?"

Direct skill invocation:

/skill retrospecting

What to Expect

Process Flow

1. Scope Definition - You'll be asked:

• Time range or commit range for the session
• What you were trying to accomplish
• How detailed of an analysis you need (quick/standard/comprehensive)

2. Data Collection - The skill will:

• Analyze git history for the session timeframe
• Parse Claude Code native session logs from ~/.claude/projects/{project-dir}/{session-id}.jsonl
• Examine changed files and code quality
• Gather your feedback through targeted questions

3. Analysis & Report - You'll receive:

• Structured retrospective report (markdown format)
• Evidence-based findings with specific examples
• Prioritized recommendations
• Patterns worth replicating or avoiding

4. Validation & Refinement - You can:

• Confirm the analysis matches your experience
• Add pain points that were missed
• Prioritize which improvements matter most
• Request configuration updates based on findings

5. Cleanup (Optional) - You can:

• Delete the session log files after analysis
• Keep them for future reference

Time Investment

• Quick retrospective: 5-10 minutes (brief summary)
• Standard retrospective: 15-20 minutes (balanced analysis)
• Comprehensive retrospective: 30+ minutes (detailed deep-dive)

The skill will recommend a depth based on your session size (commits, log volume, complexity).

Output Format

Report Types

Quick Retrospective - Concise summary with:

• Highlights (top successes)
• Challenges (main issues)
• Key learnings
• 2-3 action items

Comprehensive Retrospective - Detailed analysis with:

• Executive summary with metrics
• Success patterns with evidence
• Pain points with root causes
• Workflow optimization analysis
• Prioritized recommendations
• Patterns for future reference

Report Storage

All reports are saved to:

${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/YYYY-MM-DD-description-SESSION_ID.md

Example:

${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/2025-10-23-authentication-refactor-3be2bbaf.md

The session ID links the report to the original conversation logs for traceability.

File Organization

${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/
├── README.md                    # This file (user documentation)
├── SKILL.md                     # Skill instructions (for Claude)
├── contexts/
│   └── session-analytics.md    # Analysis framework (auto-loaded)
├── templates/
│   └── retrospective-templates.md  # Report templates (auto-loaded)
├── reports/
│   └── YYYY-MM-DD-*.md         # Generated retrospective reports
└── scripts/
    └── analyze-session-logs.sh # Session log analysis helper

Session logs are stored by Claude Code in:
~/.claude/projects/{project-dir}/{session-id}.jsonl
(where {project-dir} is your working directory path with slashes replaced by dashes)

Configuration

Retrospective Depth

You can request a specific depth level:

• Quick: Fast summary for simple sessions
• Standard: Balanced analysis for typical sessions
• Comprehensive: Deep dive for complex or significant sessions
• Custom: Focus on specific areas you define

The skill will suggest an appropriate depth based on session metrics, but you can override.

Focus Areas

You can request focus on specific aspects:

• "Focus on code quality and testing"
• "Analyze communication effectiveness"
• "Look for security considerations we might have missed"
• "Compare this session to previous similar work"

Integration with Other Features

Configuration Improvements

If the retrospective identifies patterns that should become standard practice, the skill will:

1. Suggest updates to .claude/CLAUDE.md, SKILL.md files, or agent definitions 2. Show you the proposed changes 3. Apply them with your approval

This creates a continuous improvement loop.

Pattern Libraries

Successful patterns and anti-patterns are extracted into reusable libraries (future feature):

${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/patterns/
├── successful-patterns.md
└── anti-patterns-to-avoid.md

Log Cleanup

After generating a report, you can optionally delete the session logs to reduce repository size. The retrospective report preserves key insights, so logs are often not needed afterward.

Tips for Best Results

Provide Clear Session Goals

When asked "What were you trying to accomplish?", be specific:

• Good: "Refactor authentication to use biometric providers and add unit tests"
• Less helpful: "Work on authentication"

Be Honest About Pain Points

The skill asks for feedback about friction areas. Candid input leads to better insights:

• Where did you get confused?
• What took longer than expected?
• What would you change about the workflow?

Use Retrospectives Regularly

• After major features: Capture complex implementation insights
• Weekly/sprint boundaries: Track progress and improvement trends
• After challenging sessions: Learn from difficulties
• After smooth sessions: Identify what made them effective

Follow Up on Recommendations

Retrospectives are most valuable when recommendations are acted upon:

• Implement high-priority improvements in next session
• Update configuration files with better practices
• Share learnings with team (if applicable)

Troubleshooting

"Session logs not found"

• Session logs are automatically generated by Claude Code in ~/.claude/projects/{project-dir}/
• Project directory is derived from your working directory (slashes replaced with dashes)
• Example: /Users/user/project → ~/.claude/projects/-Users-user-project/
• You can still do a retrospective using git history + your feedback if logs are unavailable

"Report seems generic"

• Provide more specific session goals upfront
• Add detailed feedback when prompted
• Request a comprehensive retrospective for deeper analysis

"Analysis doesn't match my experience"

• The validation step (Step 6) is exactly for this
• Tell the skill what's missing or incorrect
• It will refine the analysis based on your input

"Context window exceeded"

• Request a "quick" retrospective for large sessions
• The skill will summarize logs instead of reading them fully
• Focus on specific areas rather than comprehensive analysis

Privacy & Security

What Data is Analyzed

• Git commits and diffs visible in your repository
• Claude Code native session logs from ~/.claude/projects/{project-dir}/{session-id}.jsonl
• File contents of changed files
• Your explicit feedback responses

Data Storage

• All analysis happens locally in your session
• Reports stored in your repository (${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/)
• No data sent to external services
• Logs can be deleted after retrospective if desired

Sensitive Information

If your session involved sensitive data:

• Review generated reports before committing them
• Retrospective can be run without committing reports
• You can request specific sections be excluded from the report

Examples

Example 1: Quick Post-Session Review

User: "Can you do a quick retrospective on what we just did?"

Process:

1. Skill checks: 8 commits, 3 log files, ~45 minutes of work 2. Suggests: Quick retrospective (5-10 min) 3. Analyzes git changes, skims logs, asks 2-3 questions 4. Generates quick report with highlights, challenges, learnings 5. Takes ~7 minutes total

Example 2: Comprehensive Feature Analysis

User: "I want a detailed retrospective on the entire authentication refactor we did today"

Process:

1. Skill checks: 34 commits, 12 log files, ~4 hours of work 2. Recommends: Comprehensive retrospective (30 min) 3. Deep analysis of git history, detailed log parsing, code quality metrics 4. Extensive user feedback gathering (7-10 questions) 5. Generates full report with metrics, patterns, recommendations 6. Suggests 3 configuration improvements for .claude/CLAUDE.md 7. Offers to delete logs after report validated

Example 3: Focus on Specific Issues

User: "Analyze why testing took so long this session"

Process:

1. Skill identifies custom focus: testing workflow 2. Examines test-related commits and file changes 3. Searches logs for test failures, retry patterns 4. Asks targeted questions about testing pain points 5. Generates focused report on testing efficiency with specific recommendations

Future Enhancements

Planned improvements to this skill:

• Automated CI integration (run retrospectives on PR merge)
• Trend analysis across multiple sessions
• Pattern library with searchable best practices
• Comparative analysis (this session vs similar past sessions)
• Team retrospectives (multi-user session analysis)

Feedback

Found an issue or have a suggestion? Update the skill:

• Modify ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/SKILL.md (Claude's instructions)
• Modify this README.md (user documentation)
• Add context files in contexts/ for additional analysis frameworks
• Update templates in templates/ for different report formats

Retrospective Report Templates

Purpose: Standardized templates for comprehensive session retrospectives Owner: Retrospective Skill Storage: All reports generated in ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/ directory Session Logs: Claude Code native logs stored in ~/.claude/projects/{project-dir}/{session-id}.jsonl

---

Template 1: Comprehensive Session Retrospective

# Session Retrospective - [Project Name] [Session Date]

**Session ID**: [Unique identifier]
**Duration**: [Start time] - [End time] ([Total duration])
**Scope**: [Brief description of session goals]
**Outcome**: [SUCCESS/PARTIAL/NEEDS_FOLLOW_UP]

---

## Executive Summary

### Key Achievements

- [Major accomplishments from the session]
- [Quantitative metrics: lines of code, files created, tests added]
- [Quality outcomes: test coverage %, standard compliance]

### Success Metrics

| Metric               | Target | Achieved | Status   |
| -------------------- | ------ | -------- | -------- |
| Task Completion Rate | 90%    | X%       | ✅/⚠️/❌ |
| Compilation Success  | 100%   | X%       | ✅/⚠️/❌ |
| Test Coverage        | 80%    | X%       | ✅/⚠️/❌ |
| Code Quality Score   | 8/10   | X/10     | ✅/⚠️/❌ |

---

## What Went Well

### Successful Workflow Patterns

1. **[Pattern Name]**: [Description]
   - **Evidence**: [Specific examples from session with file:line references]
   - **Impact**: [Quantified benefit - time saved, quality improved, etc.]
   - **Replicability**: [How to repeat this success in future sessions]

2. **[Pattern Name]**: [Description]
   - **Evidence**: [Specific examples from session]
   - **Impact**: [Quantified benefit]
   - **Replicability**: [How to repeat success]

### Quality Achievements

- **Architecture Compliance**: [Specific examples of well-implemented patterns]
- **Test Coverage**: [Coverage metrics and thoroughness of tests]
- **Security Standards**: [Security best practices followed]
- **Performance**: [Performance optimizations or considerations]

### Communication & Collaboration

- **Effective Interactions**: [What communication patterns worked well]
- **Clear Requirements**: [Examples of well-defined tasks]
- **Useful Feedback**: [Valuable user input that improved outcomes]

---

## Pain Points & Challenges

### Workflow Friction Areas

1. **[Issue Category]**: [Description]
   - **Root Cause**: [Analysis of underlying cause]
   - **Impact**: [Quantified impact - time lost, quality affected, etc.]
   - **Frequency**: [How often this occurred]
   - **Prevention Strategy**: [How to avoid in future sessions]

2. **[Issue Category]**: [Description]
   - **Root Cause**: [Analysis of underlying cause]
   - **Impact**: [Quantified impact on workflow]
   - **Prevention Strategy**: [How to avoid in future]

### Technical Challenges

- **Compilation Issues**: [Number of failures, causes, resolution]
- **Test Failures**: [Test-related problems and how they were resolved]
- **Tool Limitations**: [Constraints or issues with available tools]
- **Integration Problems**: [Difficulties combining components or changes]

### Communication Gaps

- **Unclear Requirements**: [Cases where instructions were ambiguous]
- **Missing Context**: [Information that should have been provided upfront]
- **Assumption Mismatches**: [Differences between expected and actual outcomes]

---

## Improvement Recommendations

### Immediate Actions (Next Session)

1. **[High Priority Item]**: [Specific action with expected impact]
2. **[High Priority Item]**: [Specific action with expected impact]
3. **[High Priority Item]**: [Specific action with expected impact]

### Short-term Enhancements (1-2 weeks)

1. **[Enhancement Area]**: [Description and implementation approach]
2. **[Enhancement Area]**: [Description and implementation approach]

### Long-term Vision (1-3 months)

1. **[Strategic Improvement]**: [Long-term enhancement with roadmap]
2. **[Strategic Improvement]**: [Long-term enhancement with roadmap]

---

## Workflow Optimization Analysis

### Cycle Time Analysis

- **Average Task Duration**: [Time from start to completion]
- **Rework Frequency**: [% of tasks requiring significant revision]
- **Bottlenecks**: [Where workflow got stuck or slowed]
- **Efficiency Wins**: [What made progress faster]

### Quality Progression

- **Code Quality Trend**: [Quality improvement over session duration]
- **Test Coverage Trend**: [Coverage changes over time]
- **Standard Compliance**: [Adherence to project guidelines]
- **Learning Evidence**: [Signs of improving effectiveness during session]

### Tool & Resource Usage

- **Tool Effectiveness**: [Which tools were most/least effective]
- **Context Sufficiency**: [Was enough context available]
- **Documentation Quality**: [Usefulness of available documentation]

---

## Patterns for Future Reference

### Successful Patterns to Replicate

1. **[Pattern Name]**: [Description and replication instructions]
2. **[Pattern Name]**: [Description and replication instructions]

### Anti-Patterns to Avoid

1. **[Anti-Pattern Name]**: [Description and prevention strategy]
2. **[Anti-Pattern Name]**: [Description and prevention strategy]

### Context-Specific Learnings

- **Project Type**: [Insights specific to this type of project]
- **Task Complexity**: [Approaches that worked for this complexity level]
- **Tech Stack**: [Technology-specific patterns discovered]

---

## Sub-agent Feedback (if applicable)

### [Sub-agent Name] Feedback

- **Strengths**: [What worked well in this sub-agent's tasks]
- **Challenges**: [What caused difficulty or confusion]
- **Suggestions**: [Recommendations for improved coordination]

### [Sub-agent Name] Feedback

- **Strengths**: [What worked well]
- **Challenges**: [What caused difficulty]
- **Suggestions**: [Recommendations for improvement]

---

## User Experience Summary

### Most Valuable Aspects

- [What the user found most helpful about this session]
- [Specific features or approaches that delivered value]

### Friction Points

- [What caused user frustration or confusion]
- [Process inefficiencies from user perspective]

### Desired Improvements

- [User suggestions for enhancement]
- [Features or capabilities user wishes were available]

---

## Next Session Preparation

### Workflow Optimizations to Implement

- [ ] [Specific workflow change based on learnings]
- [ ] [Process improvement to apply next session]
- [ ] [Tool usage optimization to implement]

### Context Enhancements

- [ ] [Additional context to provide upfront]
- [ ] [Documentation updates needed]
- [ ] [Reference materials to prepare]

### Success Criteria

- [ ] [Define clear goals for next session]
- [ ] [Establish metrics to track]
- [ ] [Identify resources needed]

---

**Report Generated**: [Date/Time]
**Generated By**: Retrospective Skill
**Next Review**: [Scheduled follow-up date]

---

Template 2: Quick Retrospective

# Quick Retrospective - [Session Topic]

**Date**: [Date]
**Duration**: [Duration]
**Scope**: [One-line description of what was accomplished]

## Highlights ✅

- [Top success with specific example]
- [Key achievement with measurable outcome]
- [Quality win or best practice followed]

## Challenges ⚠️

- [Main technical challenge and resolution]
- [Process friction point]
- [Communication or clarity issue]

## Key Learnings 💡

- [Important pattern discovered]
- [Approach to replicate in future]
- [Anti-pattern to avoid next time]

## Action Items 🚀

- [ ] [Immediate improvement to implement]
- [ ] [Follow-up task for next session]
- [ ] [Documentation or context update needed]

**Quick Assessment**: [1-2 sentence overall evaluation of session effectiveness]

---

Template Usage Guidelines

When to Use Each Template

Comprehensive Template:

• End of major feature implementations
• Completion of multi-day or multi-task sessions
• When significant learnings emerged
• User requests detailed analysis
• Sessions with noteworthy successes or challenges

Quick Template:

• Regular session wrap-ups
• Single-task completions
• Brief work sessions (< 1 hour)
• Routine maintenance or updates
• User requests lightweight summary

Storage and Organization

${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/
├── SKILL.md
├── contexts/
│   └── session-analytics.md
├── templates/
│   └── retrospective-templates.md
├── reports/
│   ├── YYYY-MM-DD-brief-description-SESSION_ID.md
│   └── YYYY-MM-DD-another-session-SESSION_ID.md
├── patterns/
│   ├── successful-patterns.md
│   └── anti-patterns-to-avoid.md
└── scripts/
    └── analyze-session-logs.sh

Session logs (managed by Claude Code):
~/.claude/projects/{project-dir}/{session-id}.jsonl
(where {project-dir} = working directory path with slashes replaced by dashes)

Naming Convention: YYYY-MM-DD-brief-description-SESSION_ID.md

• Use ISO date format for chronological sorting
• Keep description concise (3-5 words)
• Use hyphens for readability
• Include session ID from log files for traceability

Pattern Library Maintenance:

• Extract reusable patterns from retrospectives in patterns/ directory
• Update patterns as new evidence emerges
• Organize by project type, technology, or problem domain
• Reference specific retrospectives as evidence

---

These templates provide structured frameworks for capturing session insights and generating actionable recommendations for continuous improvement.