Session Analysis

Quick Start

If you need to analyze a session: Read the transcript, extract metrics, identify patterns, and summarize findings.

If you need to compare sessions: Load multiple transcripts, identify trends, and track improvement over time.

If you need to generate a report: Output structured markdown with findings, metrics, and action items.

Session Data Structure

Files to Read

Transcript Format

Each line is a JSON message:

{"message":{"content":[{"type":"text","text":"User request"},{"type":"tool_use","name":"Read","input":{"file_path":"..."}}],"role":"user"},"timestamp":"..."}

Extract:

• message.content[].type - message type (text, tool_use, tool_result)
• message.content[].text - actual content
• message.role - user or assistant

Analysis Framework

Phase 1: Load & Basic Metrics

1. Read transcript JSONL
2. Count messages by type
3. Calculate session duration (start → end timestamps)
4. Extract tool usage frequency
5. Identify session branch/context

Phase 2: Pattern Detection

Phase 3: Mistake Identification

Common categories:

1. Skill gap - Task done manually when skill exists
2. Context miss - Acting without reading relevant files
3. Over-engineering - Complex solution for simple problem
4. Under-engineering - Simple solution for complex problem
5. Tool misuse - Wrong tool for the job
6. Validation skip - No verification after action

Phase 4: Improvement Extraction

For each mistake pattern:

- What happened
- Why it happened (root cause)
- How to prevent it
- Skill or rule that could help

Output Format

# Session Analysis: {session_id}

## Summary
- Duration: {start} → {end}
- Total messages: {n}
- Tool invocations: {n}
- Skills invoked: {n}

## Key Patterns

### Positive Patterns
- [Pattern description with evidence]

### Improvement Areas
- [Pattern description with evidence]
- [Root cause]
- [Suggested fix]

## Mistakes Analysis

| Mistake | Count | Severity | Root Cause |
| :--- | :--- | :--- | :--- |
| [Type] | n | high/med/low | [Cause] |

## Recommendations

1. [Actionable improvement]
2. [Skill to invoke]
3. [Rule to add]

Practical Examples

Example 1: Analyze Previous Session

# Read previous session transcript
Read .claude/workspace/sessions/previous-session.jsonl

# Parse and analyze
# Extract messages, tools, timestamps
# Generate report

Example 2: Compare Two Sessions

# Load both transcripts
Read .claude/workspace/sessions/{id1}/raw-transcript.jsonl
Read .claude/workspace/sessions/{id2}/raw-transcript.jsonl

# Compare metrics
# Identify trends
# Output comparison

Example 3: Extract Training Data

# Find recurring mistakes
# Categorize by type
# Generate improvement suggestions
# Output as actionable items

Common Analysis Tasks

Task: Post-Session Review

1. Read previous-session.jsonl
2. Extract all tool calls and their outcomes
3. Identify any user corrections ("No", "Wrong", "Wait")
4. Count skill invocations vs direct tool use
5. Generate improvement suggestions

Task: Trend Analysis

1. Load last 3 session transcripts
2. Calculate metrics for each
3. Track improvement/decline
4. Identify persistent issues
5. Recommend focused improvement

Task: Skill Gap Analysis

1. Count Skill(...) invocations
2. Identify tasks that could use skills but didn't
3. Cross-reference with available skills
4. Suggest missing skills or skill adoption

Command Aliases

For quick analysis, use these patterns:

Output Best Practices

1. Lead with summary - Top-level findings first
2. Include evidence - Quote from transcript
3. Be specific - File paths, line numbers
4. Actionable - Each finding has a next step
5. Quantified - Use metrics when possible