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

Process

1. Determine mode — Session or periodic based on user request
2. Gather data — From context (session) or JSONL extraction (periodic — see references/extraction-patterns.md)
3. Detect patterns — Walk through all analysis categories below
4. Score findings — High/Medium/Low impact based on frequency and token/time cost
5. Generate report — docs/audits/SESSION_REFLECTION_YYYY-MM-DD.md
6. Present findings — Summarize 3-5 key findings to the user
7. 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

Workflow Gaps

Lightweight Skill Effectiveness

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

Resistance Patterns

Detailed References

• references/extraction-patterns.md — JSONL schema, jq extraction commands, session file discovery for periodic mode