Analyze History

Conversation History Analysis

Extract patterns, recurring errors, architectural decisions, and actionable recommendations from past Claude Code sessions for the current project.

When to Use

• User asks about past conversations, patterns, or project history
• User wants to find recurring errors or issues
• User asks for a retrospective or lessons learned
• User wants to know which areas of the codebase get the most churn
• User asks "what have we done", "what keeps going wrong", "what should we remember"
• User wants to review project evolution across sessions

Workflow

Phase 1: Determine Scope

1. Identify the project path. Default to the current working directory.
2. Determine analysis depth. If not specified, ask:
   • quick -- Stats only: session counts, tool usage, file hotspots
   • standard -- Full extraction: keyword theming, error classification, decisions
   • deep -- Also processes subagent files, richer context per finding
3. Check for cached results. Look for ~/.claude/projects/{encoded-path}/.analysis-cache/manifest.json. If a recent cache exists and the user hasn't requested fresh analysis, offer to reuse it.

Path encoding rule: replace every / in the absolute project path with -. For example, /home/user/projects/foo becomes -home-user-projects-foo (the leading / becomes the leading -).

Phase 2: Preprocess

Run the extraction script:

python3 ~/.claude/skills/analyze-history/scripts/extract.py --project {path} --mode {mode}

Optional flags:

• --raw to include all raw user requests alongside keyword themes (additive, not exclusive)
• --since {YYYY-MM-DD} for recent-only analysis

After the script completes, report to the user:

• Number of sessions processed
• Date range covered
• Processing time

If the script fails, check that the project path is correct and that JSONL session files exist at ~/.claude/projects/{encoded-path}/.

Phase 3: Analyze, Auto-Escalate, and Cross-Reference

Read ~/.claude/projects/{encoded-path}/.analysis-cache/insights.json.

Start with the summary section -- it contains key metrics (sessions, errors, compactions, corrections detected, theme quality verdict, top themes, top errors, top tools) in a compact block that fits in a single read. Use this to orient the analysis before diving into details.

Corrections & Repeated Instructions

The corrections array contains user messages flagged by the correction detector (redirections, quality feedback, reminders, preferences, execution model changes). These are the highest-signal data points for understanding what the user repeatedly has to tell the AI. Group them by pattern and cross-reference with raw_requests_sample for additional context.

Theme Auto-Escalation

Inspect theme_quality.quality_verdict in the insights:

Error Auto-Escalation

• If error_patterns returns 0 classified patterns but unclassified_errors_sample count > 5, scan the raw error samples and identify groupings manually.
• If decisions count is 0 but session count > 5, note this gap and suggest re-running with --mode deep to analyze subagent conversations.

Cross-Referencing

• CLAUDE.md: Read the project's CLAUDE.md (if it exists). Identify which discovered patterns are already documented vs. genuinely new.
• Serena memories: If available, call list_memories and read relevant memories. Note patterns that corroborate or contradict findings.

Phase 4: Present Findings

Use this structure for the output:

## Project History Analysis: {project name}

### Overview
- Sessions: X | Date range: YYYY-MM-DD to YYYY-MM-DD
- Interactions: X user messages | X context compactions | X corrections detected
- Top tools: Bash (X), Edit (X), Read (X)

### Recurring Errors (by confidence)
#### High Confidence (>50% of sessions)
| Pattern | Type | Count | Sessions | Example |

#### Medium Confidence (20-50%)
| Pattern | Type | Count | Sessions | Example |

#### Emerging (<20%)
| Pattern | Type | Count | Sessions | Example |

### Codebase Hot Spots
| File | Edits | Reads | Last Touched |
Top 15 most-modified files.

### User Corrections & Repeated Instructions
Group corrections by pattern (ranked by frequency):
1. **[Pattern name]** (Nx occurrences)
   - [Correction example] -- session: {slug}
   - [Correction example] -- session: {slug}
   What it means: [Interpretation of what the user keeps having to say]
...

### Key Decisions & Course Corrections
1. [Decision text] -- session: {slug}, {date}
   Trigger: {keyword|user correction}
...

### Request Patterns
| Theme | Count | % Sessions | Examples |
...

### Already Documented (in CLAUDE.md / Serena memories)
- [Pattern X] -- already captured in {source}
...

### New Insights (not yet documented)
- [Pattern Y] -- appears in N sessions, recommend adding to CLAUDE.md
...

### Actionable Recommendations
1. **[Priority]**: [Recommendation] -- based on [evidence]
...

Omit any section that has no data rather than showing an empty table.

Phase 5 (Optional): Deep Dive

If the user asks about a specific session, pattern, or decision:

• Use session slugs or IDs from the insights to locate specific JSONL files at ~/.claude/projects/{encoded-path}/{session-id}.jsonl.
• Grep or read those files for full context around the topic of interest.
• Summarize relevant excerpts rather than dumping raw JSONL.

Phase 6 (Optional): Persist Insights

If significant new patterns were found, offer to:

• Update the project's CLAUDE.md with new lessons learned (append to an appropriate section)
• Create or update Serena memories with new findings (if Serena is available)

Only persist if the user agrees. Do not auto-modify CLAUDE.md without confirmation.

Bias Awareness

Apply these corrections throughout the analysis:

• Normalize by session count (session_ratio), not raw count. A single marathon session with 50 errors should not outweigh a pattern that appears once in each of 10 sessions.
• Do not over-weight recent sessions. Always report first_seen and last_seen dates, not just last occurrence. A pattern from 3 months ago that stopped recurring is different from one that appeared yesterday.
• Separate tool errors from conceptual errors. Transient failures (network timeouts, file permission issues, flaky tests) are less actionable than systemic mistakes (wrong architecture, repeated misunderstanding of an API). Classify and label accordingly.
• Distinguish correlation from causation. "File X is edited often" means it's actively developed, not necessarily problematic. Pair edit frequency with error frequency to identify genuinely troubled files.
• Note small sample sizes. If fewer than 5 sessions exist, state that confidence is limited and recommendations are preliminary. Do not present weak signals as strong patterns.
• Watch for survivorship bias. Sessions where everything went smoothly may not generate notable log entries. Absence of errors in history does not mean absence of problems.

Important Notes

• The extraction script must exist at ~/.claude/skills/analyze-history/scripts/extract.py before this skill can run. If it is missing, inform the user and offer to help create it.
• All file paths in output should be relative to the project root for readability.
• When presenting errors, include enough context (file, line range, error message) to be actionable without requiring the user to re-read entire sessions.
• If the project has no conversation history yet, say so clearly rather than producing an empty analysis.
• For large projects with many sessions (>50), recommend starting with --since to scope the analysis to a relevant time window, then broadening if needed.