mining-session-patterns

Extract actionable patterns from Claude Code session JSONL files. Surfaces error→fix sequences, tool failure rates, and cost-per-story signals for compound learning.

SKILL.md

GitHub

Session Pattern Mining

Target: $ARGUMENTS

Mines Claude Code session transcripts for recurring patterns that feed compound learning. Converts raw session data into actionable improvements.

Arguments

Position Name Required Default Description
1 time-range no 7d Period to scan. E.g. 7d, 30d, this-week.
2 output-path no docs/patterns/session-patterns.md Where to write findings.

Examples:

/mining-session-patterns                    # Last 7 days, default output
/mining-session-patterns 30d                # Last 30 days
/mining-session-patterns 7d ./patterns.md   # Custom output path

Data Source

~/.claude/projects/*/*.jsonl    # Session transcripts

Critical: Never bulk-read full .jsonl files. Use sampling strategy below to respect context budget.

Workflow

  1. Discover session files — Glob ~/.claude/projects/*/*.jsonl. Filter by mtime within time-range. Select up to 10 files, preferring recent.

  2. Sample each file — Read first 20 lines + last 20 lines per file. This captures session setup (tools, config) and final outcomes (errors, completions). Skip files smaller than 5 lines.

  3. Extract patterns from sampled lines:

    • Error-fix sequences: Tool call with error response followed by a successful retry or different approach. Look for type: "tool_error" or error messages in tool results, then the next tool call on the same target.
    • Tool failure rates: Count tool calls and failures per tool type (Bash, Edit, Read, Grep, Glob, Write). A failure is any tool result containing error indicators.
    • Cost signals: Estimate token usage per session from message counts and approximate message sizes. Map to task complexity (small/medium/large) based on message count thresholds: <20 small, 20-80 medium, >80 large.
  4. Format findings — Structure as tables per Output Format below. Every row must suggest a concrete improvement or be omitted.

  5. Write output — Write to output-path. Create parent directories if needed.

Output Format

# Session Patterns — <start-date> to <end-date>

## Error-Fix Sequences
| Error Pattern | Recovery Strategy | Frequency | Candidate Learning |
|---------------|-------------------|-----------|-------------------|
| <tool>: <error summary> | <what worked> | N occurrences | <rule or skill suggestion> |

## Tool Failure Rates
| Tool | Calls | Failures | Rate | Common Cause |
|------|-------|----------|------|--------------|
| Bash | N | N | N% | <top failure reason> |

## Cost Signals
| Session | Messages | Est. Tokens | Task Complexity |
|---------|----------|-------------|-----------------|
| <uuid-short> | N | ~Nk | small/medium/large |

## Recommended Actions
- <Concrete improvement derived from patterns above>

Quality Check

  • Every table row is actionable — suggests a specific improvement
  • Findings trace to specific session files (cite UUID prefix)
  • Output stays under ~100 lines — summarize, don't dump
  • Correct > Complete > Minimal (ACE-FCA)
  • If no meaningful patterns found, say so explicitly rather than padding

Common Pitfalls

  • Reading full transcripts: Sample only. First 20 + last 20 lines.
  • Max 10 files: Don't exceed. Prefer recent files over completeness.
  • False patterns: 1-2 occurrences are anecdotes, not patterns. Minimum 3 occurrences before reporting as a pattern.
  • Data dumps: Interpret the data. Raw counts without analysis are noise.