introspect

What this skill does

# Introspect

Extract actionable intelligence from Claude Code session logs. For general JSONL analysis patterns (filtering, aggregation, cross-file joins), see the `log-ops` skill.

## cc-session CLI

The `scripts/cc-session` script provides zero-dependency analysis (requires only jq + bash). Auto-resolves the current project and most recent session.

```bash
# Copy to PATH for global access
cp skills/introspect/scripts/cc-session ~/.local/bin/
# Or on Windows (Git Bash)
cp skills/introspect/scripts/cc-session ~/bin/
```

### Commands

| Command | What It Does |
|---------|-------------|
| `cc-session overview` | Entry counts, timing, tool/thinking totals |
| `cc-session tools` | Tool usage frequency (sorted) |
| `cc-session tool-chain` | Sequential tool call trace with input summaries |
| `cc-session thinking` | Full thinking/reasoning blocks |
| `cc-session thinking-summary` | First 200 chars of each thinking block |
| `cc-session errors` | Tool results containing error patterns |
| `cc-session conversation` | Reconstructed user/assistant turns |
| `cc-session files` | Files read, edited, written (with counts) |
| `cc-session turns` | Per-turn breakdown (duration, tools used) |
| `cc-session agents` | Subagent spawns with type and prompt preview |
| `cc-session cost` | Rough token/cost estimation |
| `cc-session timeline` | Event timeline with timestamps |
| `cc-session summary` | Session summaries (compaction boundaries) |
| `cc-session search <pattern>` | Search across sessions (text content) |

### Options

```
--project, -p <name>    Filter by project (partial match)
--dir, -d <pattern>     Filter by directory pattern in project path
--all                   Search all projects (with search command)
--recent <n>            Use nth most recent session (default: 1)
--json                  Output as JSON instead of text
```

### Examples

```bash
cc-session overview                              # Current project, latest session
cc-session tools --recent 2                      # Tools from second-latest session
cc-session tool-chain                            # Full tool call sequence
cc-session errors -p claude-mods                 # Errors in claude-mods project
cc-session thinking | grep -i "decision"         # Search reasoning
cc-session search "auth" --all                   # Search all projects
cc-session turns --json | jq '.[] | select(.tools > 5)'  # Complex turns
cc-session files --json | jq '.edited[:5]'       # Top 5 edited files
cc-session overview --json                       # Pipe to other tools
```

## Analysis Decision Tree

```
What do you want to know?
|
|- "What happened in a session?"
|  |- Quick overview ---- cc-session overview
|  |- Full conversation -- cc-session conversation
|  |- Timeline ---------- cc-session timeline
|  |- Summaries --------- cc-session summary
|
|- "How was I using tools?"
|  |- Frequency ---------- cc-session tools
|  |- Call sequence ------- cc-session tool-chain
|  |- Files touched ------- cc-session files
|
|- "What was I thinking?"
|  |- Full reasoning ------ cc-session thinking
|  |- Quick scan ---------- cc-session thinking-summary
|  |- Topic search -------- cc-session thinking | grep -i "topic"
|
|- "What went wrong?"
|  |- Tool errors --------- cc-session errors
|  |- Debug trajectory ---- cc-session tool-chain (trace the sequence)
|
|- "Compare sessions"
|  |- Tool usage diff ----- cc-session tools --recent 1 vs --recent 2
|  |- Token estimation ---- cc-session cost
|
|- "Search across sessions"
|  |- Current project ----- cc-session search "pattern"
|  |- All projects -------- cc-session search "pattern" --all
```

## Session Log Schema

### File Structure

```
~/.claude/
|- projects/
|   |- {project-path}/                        # e.g., X--Forge-claude-mods/
|       |- sessions-index.json                # Session metadata index
|       |- {session-uuid}.jsonl               # Full session transcript
|       |- agent-{short-id}.jsonl             # Subagent transcripts
```

Project paths use double-dash encoding: `X:\Forge\claude-mods` -> `X--Forge-claude-mods`

### Entry Types

| Type | Role | Key Fields |
|------|------|------------|
| `user` | User messages + tool results | `message.content[].type` = "text" or "tool_result" |
| `assistant` | Claude responses | `message.content[].type` = "text", "tool_use", or "thinking" |
| `system` | Turn duration, compaction | `subtype` = "turn_duration" (has `durationMs`) or "compact_boundary" |
| `progress` | Hook/tool progress events | `data.type`, `toolUseID`, `parentToolUseID` |
| `file-history-snapshot` | File state checkpoints | `snapshot`, `messageId`, `isSnapshotUpdate` |
| `queue-operation` | Message queue events | `operation`, `content` |
| `last-prompt` | Last user prompt cache | `lastPrompt` |
| `summary` | Compaction summaries | `summary`, `leafUuid` |

### Content Block Types (inside message.content[])

| Block Type | Found In | Fields |
|-----------|----------|--------|
| `text` | user, assistant | `.text` |
| `tool_use` | assistant | `.id`, `.name`, `.input` |
| `tool_result` | user | `.tool_use_id`, `.content` |
| `thinking` | assistant | `.thinking`, `.signature` |

### Common Fields (all entry types)

```
uuid, parentUuid, sessionId, timestamp, type,
cwd, gitBranch, version, isSidechain, userType
```

## Session Log Retention

By default, Claude Code deletes sessions inactive for 30 days (on startup). Increase to preserve history for analysis.

```json
// ~/.claude/settings.json
{
  "cleanupPeriodDays": 90
}
```

Currently set to 90 days. Adjust based on disk usage (`dust -d 1 ~/.claude/projects/`).

## Quick jq Reference

For one-off queries when cc-session doesn't cover your need:

```bash
# Pipe through cat on Windows (jq file args can fail)
cat session.jsonl | jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | .name'

# Two-stage for large files
rg '"tool_use"' session.jsonl | jq -r '.message.content[]? | select(.type == "tool_use") | .name'
```

## Session Insights

After running any analysis, **always** generate a "Session Insights" section with actionable recommendations. The tone should be friendly and mentoring - a helpful colleague who noticed some patterns, not a critic.

### What to Look For

Scan the session data for these patterns and generate recommendations where relevant:

**Tool usage improvements:**
- Using `Bash(grep ...)` or `Bash(cat ...)` instead of Grep/Read tools - suggest the dedicated tools
- Repeated failed tool calls with same input - suggest pivoting earlier
- Heavy Bash usage for tasks a skill handles - recommend the skill by name
- No use of parallel tool calls when independent reads/searches could overlap

**Workflow patterns:**
- Long sessions with no commits - suggest incremental commits
- No `/save` at session end - remind about session continuity
- Repeated context re-reading (same files read 3+ times) - suggest keeping notes or using `/save`
- Large blocks of manual work that `/iterate` could automate - mention the loop pattern
- Debugging spirals (5+ attempts at same approach) - suggest the 3-attempt pivot rule

**Skill and command awareness:**
- Manual code review without `/review` - mention the skill
- Test writing without `/testgen` - mention the skill
- Complex reasoning without `/atomise` - mention it for hard problems
- Agent spawning for tasks a skill already handles - suggest the lighter-weight option

**Session efficiency:**
- Very long sessions (100+ tool calls) - suggest breaking into focused sessions
- High error rate (>30% of tool calls return errors) - note the pattern and suggest investigation
- Excessive file reads vs edits ratio (>10:1) - might indicate uncertainty, suggest planning first

**Permission recommendations:**
This is high-value - permission prompts break flow and cost context. Scan the session for:
- Bash commands that were used successfully and repeatedly - these are candidates for `Bash(<command>:*)` allow rules
- Tool patte