htlin222/retro

Session Review Skill

Generate a structured retrospective report for the current Claude Code session.

Core Principle

Extract only human-readable content. This means:

• ✅ User messages (the human's prompts/questions/instructions)
• ✅ Agent prose responses (explanations, reasoning, summaries, answers)
• ❌ Tool calls (bash commands, file reads/writes, search queries)
• ❌ Tool results (command output, file contents, API responses)
• ❌ System messages and internal metadata

Extraction Script

A companion Python script handles robust extraction from session JSONL files:

# Extract transcript from the current project's latest session
python3 ~/.dotfiles/claude.symlink/skills/retro/extract_conversation.py --timestamps --stats

# Or target a specific project
python3 ~/.dotfiles/claude.symlink/skills/retro/extract_conversation.py --project-dir /path/to/project --timestamps --stats

# Output as structured JSON (for programmatic use)
python3 ~/.dotfiles/claude.symlink/skills/retro/extract_conversation.py --format json

# List all sessions for a project
python3 ~/.dotfiles/claude.symlink/skills/retro/extract_conversation.py --list-sessions

The script (extract_conversation.py in this skill's directory) parses Claude Code JSONL logs and:

• Keeps only user prompts and assistant prose (type: "text" blocks)
• Strips tool_use, tool_result, thinking blocks, <system-reminder> tags, progress events, and file-history snapshots
• Supports markdown, json, and plain output formats
• Auto-detects the latest session for the current or specified project
• Zero external dependencies (stdlib only)

Output Format: Bullet Points + IMRaD Structure

Use the following structure for the report. Write in Markdown with bullet points. The format adapts IMRaD (Introduction, Methods, Results, and Discussion) for session retrospectives.

Template

# Session Review — [Date] — [Brief Topic/Goal]

## Introduction (What & Why)
- **Goal**: What was the user trying to accomplish this session?
- **Context**: Any relevant background (project name, stage of work, blockers)

## Methods (How We Worked)
- **Approach**: High-level steps taken to reach the goal
- **Tools/Technologies**: Key tools, libraries, languages involved
- **Workflow Pattern**: How the conversation flowed (linear, iterative, exploratory, debugging loop, etc.)

## Results (What We Accomplished)
- **Completed**:
  - [item 1]
  - [item 2]
  - ...
- **Partially Completed**:
  - [item — what remains]
- **Not Started / Deferred**:
  - [item — reason]

## Discussion

### Efficiency Review
Where the user could have been more efficient with prompts or workflow:
- **[Issue]**: [What happened] → **Suggestion**: [Better approach]
- ...

### English Corrections
Grammar, word choice, or phrasing improvements from the user's messages:
- ❌ `[original text]` → ✅ `[corrected text]` — [brief explanation]
- ...
(If no corrections needed, write: "No corrections — messages were clear and well-written.")

### Concepts to Study Deeper
Topics that came up where deeper understanding would help:
- **[Concept]**: [Why it matters / what to explore]
- ...

### CLAUDE.md Improvement Suggestions
Suggested additions or changes to the project's CLAUDE.md based on friction points observed in this session:
- **Add**: `[suggested line or section]` — [reason: what friction it would prevent]
- **Modify**: `[existing section]` → `[suggested change]` — [reason]
- ...

Instructions for the Agent

1. Run the extraction script. Execute the companion script to get a clean transcript:

   python3 ~/.dotfiles/claude.symlink/skills/retro/extract_conversation.py --timestamps --stats
   

   This produces a markdown transcript with only user prompts and assistant prose — no tool noise. If the script fails or no session file is found, fall back to manually scanning the conversation history and mentally filtering out tool calls/results.

2. Review the extracted transcript. Read through the clean output from start to finish. Focus on:

   • What the user asked or instructed
   • What the agent explained, suggested, or decided

3. Identify the session goal. Infer from the first few user messages what the overarching objective was.

4. Catalog accomplishments. List concrete outputs: files created, bugs fixed, features implemented, decisions made.

5. Analyze efficiency. Look for patterns like:

   • Vague prompts that required multiple clarification rounds
   • Tasks that could have been batched into a single prompt
   • Missing context that caused the agent to go in the wrong direction
   • Repeated back-and-forth that a better initial prompt would have avoided
   • Manual steps that could be automated or added to CLAUDE.md

6. Correct English. Review every user message for:

   • Grammar errors (subject-verb agreement, tense, articles)
   • Word choice improvements (more precise or natural phrasing)
   • Typos or spelling
   • Be respectful — these are learning opportunities, not criticisms

7. Identify learning opportunities. Note concepts where the user:

   • Asked basic questions suggesting a knowledge gap
   • Made assumptions that turned out wrong
   • Could benefit from reading documentation or tutorials

8. Suggest CLAUDE.md improvements. Look for:

   • Repeated instructions the user gave that should be codified
   • Preferences or conventions that had to be restated
   • Project-specific knowledge that was missing and caused friction
   • Workflow patterns that should be documented

9. Write the report using the template above. Keep bullet points concise but informative. Use code formatting for file names, commands, and code references.

Tone

• Constructive and supportive — this is a learning tool, not a critique
• Specific and actionable — vague feedback is useless
• Honest — don't skip real issues to be polite

Notes

• If the session was very short or trivial, scale the report accordingly — no need to force content into every section.
• If the user's English was flawless, say so. Don't invent corrections.
• The CLAUDE.md suggestions should be practical and specific, not generic advice like "add more documentation."