Session Reflection
Overview
Analyze session history to find inefficiency patterns and workflow gaps, then propose concrete improvements. Two modes: quick end-of-session reflection or comprehensive periodic multi-session analysis.
Core principle: Evidence-based improvement. Quantify waste, propose specific fixes, implement nothing without approval.
When This Skill Activates
- End of a session (user asks to reflect)
- Periodic review (weekly/monthly)
- After a particularly frustrating or inefficient session
- When onboarding to a new project (analyze early sessions for missing docs)
Trigger phrases: "reflect on this session", "session review", "what went wrong", "workflow audit", "analyze my sessions", "how can we improve"
Mode Selection
| Situation | Mode | Why |
|---|---|---|
| "Reflect on this session" | Session | Single session, context available |
| "What went wrong today" | Session | Current work, immediate feedback |
| "Review my sessions this week" | Periodic | Cross-session patterns need JSONL data |
| "How can I improve my workflow" | Periodic | Patterns emerge across sessions |
| "Analyze the last 3 days" | Periodic | Multi-session, specific time range |
| Session mode | Periodic mode | |
|---|---|---|
| Scope | Current session context only | JSONL files from last N days (default: 7, max: 14) |
| Data source | Agent's own conversation context | jq-extracted summaries from ~/.claude/projects/ |
| Depth | Quick patterns, 5-10 min | Comprehensive cross-session analysis, 15-30 min |
| Dependencies | None | jq must be installed |
Process
- Determine mode — Session or periodic based on user request
- Gather data — From context (session) or JSONL extraction (periodic — see references/extraction-patterns.md)
- Detect patterns — Walk through all analysis categories below
- Score findings — High/Medium/Low impact based on frequency and token/time cost
- Generate report —
docs/audits/SESSION_REFLECTION_YYYY-MM-DD.md - Present findings — Summarize 3-5 key findings to the user
- User review gate — Implement only changes the user approves
Session Mode: Reflecting From Context
The agent reviews its own conversation history within the current session:
- Tool call inventory — Which tools were called, how many times, on what targets
- Decision trace — Where did the agent change direction, backtrack, or get corrected
- User corrections — Any place the user said "no, not that" or redirected the approach
- Time spent — Which steps took disproportionately long
No file I/O needed. The agent introspects on its own behavior.
Periodic Mode: JSONL Extraction
CRITICAL: Never read raw JSONL files directly. They are massive and will consume the entire context budget. Always use the jq summary extraction pipeline documented in references/extraction-patterns.md.
Use a subagent (Agent tool) to perform the extraction and analysis, keeping the main context clean.
Analysis Categories
Agent Behavior Patterns
| Pattern | Signal | Impact | Example |
|---|---|---|---|
| Repeated file reads | Same file read 3+ times | High — token waste | Read config.py 7 times across session |
| Wrong path taken | Implementation then reversal | High — time waste | Built feature, discovered existing code |
| Unnecessary tool calls | Redundant or no-op calls | Medium — token waste | Glob + Grep for something already in context |
| Context loss recovery | Re-discovering info after compaction | High — fragile workflows | Key architecture detail lost mid-session |
| Assumption without verification | Decision made, then corrected | High — rework | Assumed API shape, had to refactor |
Workflow Gaps
| Pattern | Signal | Impact | Example |
|---|---|---|---|
| Repeated manual steps | Same commands across sessions | Medium — automation opportunity | Running same 3-command setup sequence |
| Missing documentation | Agent had to discover what should be documented | Medium — onboarding friction | Figured out test setup from scratch |
| Missing skill coverage | Agent did something a skill should guide | Medium — quality risk | Ad-hoc code review without fresh-eyes |
| Recurring blockers | Same type of error/obstacle reappearing | High — systemic issue | Permission errors, env setup failures |
Lightweight Skill Effectiveness
| Pattern | Signal | Impact | Example |
|---|---|---|---|
| Skill ignored | Agent rationalized skipping an applicable skill | High — skill needs stronger triggers | Fresh-eyes applicable but agent went straight to commit |
| Skill partially followed | Agent started skill process but shortcut steps | Medium — skill may be too heavy | Started TDD but skipped red-green-refactor cycle |
| Skill fought | Agent followed skill but produced poor results | Medium — skill content needs revision | Doc audit ran but missed obvious false claims |
Report Format
Generate docs/audits/SESSION_REFLECTION_YYYY-MM-DD.md:
# Session Reflection: YYYY-MM-DD
Mode: session | periodic (N days, M sessions)
Generated: YYYY-MM-DD | Commit: abc123
## Summary
| Metric | Count |
|--------|-------|
| Sessions analyzed | 1 or N |
| Patterns detected | X |
| High impact | X |
| Medium impact | X |
## Findings
### High Impact
#### 1. [Pattern Title]
**Category:** Agent Behavior | Workflow Gap | Skill Effectiveness
**Frequency:** N occurrences across M sessions
**Evidence:** [Specific examples from session data]
**Estimated cost:** ~Nk tokens wasted | ~N minutes lost per session
---
### Medium Impact
...
## Proposed Changes
### CLAUDE.md Updates
| # | Change | Rationale | Priority |
|---|--------|-----------|----------|
| 1 | Add section on X | Discovered 3 times | High |
#### Change 1: [Title]
**Add to:** CLAUDE.md > [section]
[exact text to add — copy-paste ready]
### New Skills
[complete skill content if applicable]
### New Slash Commands
[complete command content if applicable]
### Automation (scripts, hooks)
[complete script/hook content if applicable]
Key principle: All proposals are copy-paste ready with complete text/code. No vague "consider adding documentation about X."
Anti-Patterns
| Anti-Pattern | Why It's Wrong |
|---|---|
| Reading raw JSONL files | Will consume entire context budget — always use jq extraction |
| Auto-implementing changes | Proposals need human review — reflection without consent is noise |
| Shallow pattern matching | "Read file 3 times" might be intentional (file changed) — check context |
| Reflecting mid-task | Reflection is a distinct activity, not a sidebar — finish work first |
| Boiling the ocean | Periodic mode across 30 days will still be too much — default 7, max 14 |
Resistance Patterns
| Rationalization | Reality |
|---|---|
| "This session went fine" | Fine sessions still have patterns worth catching |
| "I already know what went wrong" | Intuition misses frequency — you remember the big blocker, not the 5 small wastes |
| "I'll just remember for next time" | You won't. Write it down or it's lost |
| "The improvements are too small to bother" | 500 tokens saved x 50 sessions = 25k tokens. Small compounds. |
| "I don't have time to reflect" | 10 minutes of reflection prevents 60 minutes of repeated mistakes |
Detailed References
- references/extraction-patterns.md — JSONL schema, jq extraction commands, session file discovery for periodic mode