Session Reflection Analysis

Step 2: Generate Session Summary

CRITICAL: Do NOT read raw session files directly. They are massive and will consume your entire token budget.

First, verify jq is available:

if ! command -v jq &> /dev/null; then
    echo "ERROR: jq is required but not installed"
    echo "Install with: brew install jq (macOS) or apt install jq (Linux)"
    exit 1
fi

Then use jq to generate a 98% token-reduced summary:

# Set project dir (adjust if auto-detection didn't work)
PROJECT_DIR="$HOME/.claude/projects/-Users-harper-Public-src-2389-matrix-productivity"  # Update this path!
OUTPUT="/tmp/session-summary.jsonl"

# Optional: Only analyze sessions from last N days
DAYS_BACK=7
CUTOFF_DATE=$(date -v-${DAYS_BACK}d +%Y-%m-%d 2>/dev/null || date -d "${DAYS_BACK} days ago" +%Y-%m-%d)

# Summarize: extract user requests, tool names, assistant text (truncated)
cat "$PROJECT_DIR"/*.jsonl 2>/dev/null | jq -c '
select(.type == "user" or .type == "assistant") |
{
  type,
  ts: .timestamp,
  content: (
    if .message.content | type == "string" then
      .message.content[0:300]
    elif .message.content | type == "array" then
      [.message.content[] |
        if .type == "text" then {t: "text", v: .text[0:300]}
        elif .type == "tool_use" then {t: "tool", v: .name}
        elif .type == "tool_result" then {t: "result", len: (.content | length)}
        elif .type == "thinking" then empty
        else {t: .type}
        end
      ]
    else null
    end
  )
}' > "$OUTPUT" 2>/dev/null

echo "Summary: $(wc -l < "$OUTPUT") messages, $(wc -c < "$OUTPUT" | xargs) bytes"

This extracts:

• User message text (first 300 chars)
• Tool calls (name only, not full output)
• Tool result sizes (not content)
• Timestamps for sequence analysis

Step 3: Launch Subagent for Analysis

Use the Task tool to spawn an analysis subagent:

Task tool parameters:
- subagent_type: "Explore"
- prompt: |
    Analyze the session summary at /tmp/session-summary.jsonl for inefficiency patterns.

    Read the file and look for these patterns:

    | Pattern | Example | Impact |
    |---------|---------|--------|
    | **Wasted tokens** | Re-reading same file 5+ times | High |
    | **Wrong paths taken** | Implemented feature, then discovered existing code | Medium-High |
    | **Repeated mistakes** | Same error type in 3+ instances | Medium |
    | **Missing automation** | Manual steps repeated across sessions | Medium |
    | **Missing documentation** | Had to figure out what should be in CLAUDE.md | Medium |
    | **Unnecessary tool calls** | Called multiple tools when one would work | Low-Medium |
    | **Context loss after compaction** | Info that should survive in persistent docs | High |
    | **Assumption without verification** | Decisions made without checking existing code | High |

    For each pattern found, propose improvements as:
    1. CLAUDE.md updates
    2. New skills for .claude/skills/
    3. New slash commands for .claude/commands/
    4. Script automation
    5. Git hooks
    6. Workflow changes

    Make all proposals copy-paste ready with complete text/code.
    Quantify impact where possible (tokens saved, time saved).
    Be specific with examples from the actual session data.

Step 4: Create Reflection Document

The subagent should generate a document with this structure:

# Session Reflection: YYYY-MM-DD

## Summary Statistics
- Session date range: [start] to [end]
- Messages analyzed: [count]
- Major inefficiencies found: [count]

## Proposed Improvements

### High Priority

#### 1. [Problem Title]

**Problem observed**: [What went wrong - be specific with examples]

**Proposed solution**:

[Complete text/code to add or change - copy-paste ready]

**File to modify**: `path/to/file.md`

**Cost**: [Effort to implement, any downsides]

**Benefit**: [Time/tokens saved - quantify if possible]

---

### Medium Priority
...

### Low Priority
...

## Implementation Notes

[Cross-cutting concerns, dependencies, warnings]

Step 5: Present Findings

After analysis completes:

1. Summarize key findings - 3-5 bullet points of major inefficiencies
2. Show the reflection document path - Where to find full details
3. Ask which changes to implement - Don't auto-implement

Critical Rules

1. NEVER read raw session files directly - Always use the jq summary
2. NEVER implement changes automatically - Only propose them
3. Make proposals copy-paste ready - Complete text, not descriptions
4. Quantify impact when possible - "Saved 10K tokens" not "saves tokens"
5. Be specific with examples - "Re-read config.py 7 times" not "read files multiple times"

Example Analysis Output

High Priority Issues Found:

1. **Re-reading the same file repeatedly** (7 times in one session)
   - Propose: Add key architecture summaries to CLAUDE.md
   - Benefit: Save ~15K tokens per session

2. **Implemented feature without checking existing code first**
   - Took 3 iterations to match actual behavior
   - Propose: Add "Check existing code FIRST" rule to CLAUDE.md
   - Benefit: Prevent wrong-path implementations

3. **Manual repetitive commands**
   - Same shell commands typed each session
   - Propose: Create slash commands for common operations
   - Benefit: Save 2-3 minutes per session, prevent typos

Troubleshooting

Can't find project folder

# List all projects with recent activity
ls -lt ~/.claude/projects/ | head -10

# Search for a keyword in project names
ls ~/.claude/projects/ | grep -i "keyword"

No jsonl files found

Sessions may not have been saved yet, or the project path detection failed. Check the folder manually.

jq not installed

# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# Or use the standalone binary
curl -Lo /usr/local/bin/jq https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-macos-arm64
chmod +x /usr/local/bin/jq