/learn-from-session

name: learn-from-session
description: 'Analyze Claude Code sessions to learn what went right/wrong and suggest high-confidence improvements to skills. Use when asked to analyze a session, learn from a session, or review workflow effectiveness.'
user-invocable: true
metadata:
  internal: true

**User request**: $ARGUMENTS

Analyze a Claude Code session to identify what went well and what could be improved, then suggest high-confidence fixes to skills in this repository.

**Input formats**:

• Session ID (UUID): `184078b7-2609-46e0-a1f2-bb42367a8d34`
• Session file path: `~/.claude/projects/.../session-id.jsonl`
• Inline commentary: Text description of what happened

**Output**: High-confidence issues only with evidence-based suggestions for skill improvements.

**Signal quality bar**: Only recommend changes that would have **prevented specific rework** in the session. A fix is high-signal when ALL of: 1. You can point to exact message numbers where rework occurred 2. The skill change would have triggered BEFORE that rework 3. Following the change would have produced correct output initially

**Definition - high-signal fix**: A skill change that passes the 3/3 counterfactual test (see Phase 5.2).

---

Phase 1: Parse Input & Setup

1.1 Identify input type

| Input Pattern | Type | Action | |---------------|------|--------| | UUID format (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) | Session ID | Find and read session file | | Path ending in `.jsonl` | Session file | Read directly | | Other text | Commentary | Analyze inline, may reference sessions |

1.2 Locate session file (if session ID)

Session files are stored at:

~/.claude/projects/{project-path-encoded}/{session-id}.jsonl

**Note**: `{project-path-encoded}` replaces path separators with URL-safe encoding (e.g., `/home/user/myproject` becomes `-home-user-myproject`). Don't rely on exact path structure—use find instead.

Use Bash to find:

find ~/.claude/projects -name "*{session-id}*" -type f 2>/dev/null

**If file not found**: Ask user to provide the session file path directly or check if session ID is correct.

1.3 Create analysis log

Path: `/tmp/session-analysis-{session-id-short}-{timestamp}.md`

**Purpose**: External memory that persists findings beyond LLM working memory. Write to this file IMMEDIATELY after each discovery—never batch multiple findings into one write.

# Session Analysis Log

Session: {id or "inline commentary"}
Started: {timestamp}
Status: IN_PROGRESS

---

## Session Overview
<!-- Write immediately after Phase 2 parsing -->

**Initial request**:
**Skills invoked**:
**Outcome**:
**Session length**:

---

## Pattern Detection

### Iterations Found
<!-- Write immediately after detecting iterations - before moving to corrections -->

### User Corrections Found
<!-- Write immediately after detecting corrections - before moving to deviations -->

### Workflow Deviations Found
<!-- Write immediately after detecting deviations - before moving to missing questions -->

### Missing Questions Found
<!-- Write immediately after detecting missing questions - before moving to post-impl -->

### Post-Implementation Fixes Found
<!-- Write immediately after detecting post-impl fixes - before skill comparison -->

---

## Skill Comparison

### Skills Discovered
<!-- Write immediately after discovering which skills were used -->

### Skill: {name}
<!-- Write immediately after analyzing EACH skill - don't batch -->

---

## Potential Issues
<!-- Write each issue as identified during comparison -->

---

## Counterfactual Analysis
<!-- Write results of 3/3 test for each issue -->

---

## Final Recommendations
<!-- Populated after refresh step -->

1.4 Create todo list

**CRITICAL**: Write to log IMMEDIATELY after each finding—never batch writes.

- [ ] Setup: Create log file, parse session, write overview
- [ ] Pattern detection: iterations, corrections, deviations, missing questions, post-impl fixes (write each to log)
- [ ] Skill discovery: extract skills, locate files, write to log
- [ ] (expand: "Analyze {skill}" for each skill found)
- [ ] Refresh context: read FULL analysis log
- [ ] Counterfactual analysis: test each issue, write recommendations
- [ ] Output final report

**Expansion**: When skills are discovered, add one todo per skill:

- [ ] Analyze {skill-name} skill + write findings to log

**Why write-after-each-step matters**: By synthesis, early findings suffer context rot. Writing externalizes findings to a file that persists. The refresh step moves ALL findings to context end (highest attention zone).

---

Phase 2: Parse Session

2.1 Session file structure

Claude Code sessions are JSONL files with these record types:

| Type | Contains | |------|----------| | `user` | User messages, `message.content` field | | `assistant` | Claude responses, tool calls, thinking | | `system` | System events, commands, hooks | | `file-history-snapshot` | File state tracking |

2.2 Extract key events

Use `jq` to parse:

# User messages
cat {session-file} | jq -r 'select(.type == "user") | .message.content' 2>/dev/null

# Tool calls
cat {session-file} | jq -r 'select(.type == "assistant") | .message.content | if type == "array" then .[] | select(.type == "tool_use") | .name else empty end' 2>/dev/null

# Skill invocations
grep -o '"skill":"[^"]*"' {session-file} | sort | uniq -c

2.3 Build session overview

Extract and log:

• **Initial request**: First user message (the goal)
• **Workflow used**: Which skills invoked (`/spec`, `/plan`, `/implement`, etc.)
• **Workflow skipped**: Skills that would typically apply but weren't invoked (see table below)
• **Outcome**: Success, partial, or required rework
• **Session length**: Message count, duration if available

**Expected skills by task type** (use to detect skipped workflows):

| Task Indicators in Request | Expected Skills | |---------------------------|-----------------| | "build