retrospecting

What this skill does

# Session Retrospective Skill

## Auto-Loaded Context

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

**Retrospective Templates**: [`templates/retrospective-templates.md`](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**:

   ```bash
   # 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**:

   ```bash
   # 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**:

   ```bash
   # 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):

   ```bash
   # 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):

   ```bash
   # 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):

   ```bash
   # 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**:

   ```bash
   # 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 matc