trace-interpretation

# Trace Interpretation Guide

## Overview

ctx-monitor traces are JSONL files stored in `.claude/ctx-monitor/traces/` containing structured event records. Each line is a complete JSON object representing a single execution event.

## Event Structure

Every trace event contains these core fields:

```json
{
  "event_id": "unique-uuid",
  "session_id": "session-uuid",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "event_type": "PreToolUse|PostToolUse|SessionStart|...",
  "status": "pending|success|error",
  "tool_name": "Write|Edit|Bash|...",
  "args_preview": "truncated arguments (max 500 chars)",
  "error_message": "error details if status is error"
}
```

## Event Types

### SessionStart
Marks beginning of a Claude Code session.
- **Fields**: `session_id`, `cwd`, `timestamp`
- **Status**: `started`

### SessionEnd
Marks end of a session.
- **Fields**: `session_id`, `timestamp`
- **Status**: `ended`

### PreToolUse
Captured before a tool executes.
- **Fields**: `tool_name`, `args_preview`, `tool_use_id`
- **Status**: `pending`
- **Use**: Identify which tools were called and with what arguments

### PostToolUse
Captured after a tool completes.
- **Fields**: `tool_name`, `args_preview`, `result_preview`, `duration_ms`
- **Status**: `success` or `error`
- **Use**: Identify failures, performance issues, success rates

### SubagentStop
Captured when a subagent (Task tool) finishes.
- **Fields**: `reason`
- **Status**: `completed`
- **Use**: Track subagent lifecycle and completion reasons

### Stop
Captured when the main agent stops.
- **Fields**: `reason`
- **Status**: `completed`
- **Use**: Understand why the agent stopped (completion, error, user interrupt)

## Reading Trace Files

### File Naming
```
session_{session_id}_{timestamp}.jsonl
```

### Sessions Index
`.claude/ctx-monitor/traces/sessions.json` contains metadata:
```json
{
  "sessions": [
    {
      "session_id": "abc123",
      "started_at": "2024-01-15T10:00:00Z",
      "cwd": "/project/path",
      "event