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:

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

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"
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?"
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

Ask user to define session boundaries (time range or commit range)
Clarify session goals: "What were you trying to accomplish?"
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.

List Available Sessions:

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

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

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!)

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

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:

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
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
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
If the user approves:
- Apply the changes using the Edit tool
- Confirm what was updated
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:

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"
Explain that retrospective reports are saved separately in:
- ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/
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

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

Emergency Fallback

If approaching context limit during analysis:

Stop data collection immediately
Generate report from data gathered so far
Note in report: "Analysis limited by context constraints - [specific areas not covered]"
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:

Inform: User learns something new about their workflow
Guide: Clear next steps for improvement
Motivate: Recognition of successes encourages continued good practices
Focus: Prioritization helps user know where to invest effort
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