Parse Conversation Timeline Skill

Purpose: Transform 6MB raw conversation logs into 100-300KB structured timelines that auditors can query for compliance and efficiency analysis.

When to Use:

• Before running protocol compliance audits
• Before running protocol efficiency audits
• When investigating specific task execution patterns
• To analyze conversation structure and event sequencing

Skill Workflow

Overview: Parse conversation.jsonl → structured timeline JSON with events, file classifications, state transitions, git status, and statistics.

Phase 1: Access Conversation Data

Get Session ID from SessionStart system reminder:

✅ Session ID: 88194cb6-734b-498c-ab5d-ac7c773d8b34

Access conversation logs:

# REQUIRED: Use session ID from system reminder
SESSION_ID="88194cb6-734b-498c-ab5d-ac7c773d8b34"

# Verify session ID is provided
if [ -z "$SESSION_ID" ]; then
  echo "ERROR: Session ID not available in context." >&2
  exit 1
fi

# Main session conversation
CONV_FILE="/home/node/.config/projects/-workspace/${SESSION_ID}.jsonl"

# Verify conversation file exists
if [ ! -f "$CONV_FILE" ]; then
  echo "ERROR: Conversation file not found: $CONV_FILE" >&2
  exit 1
fi

Phase 2: Parse Timeline Events

Extract chronological events from conversation:

# Parse all events into structured timeline
jq -c 'select(.type == "user" or .type == "assistant") | {
  timestamp,
  type: (if .type == "user" then "user_message"
         elif (.message.content[]? | select(.type == "tool_use")) then "tool_use"
         elif (.message.content[]? | select(.type == "tool_result")) then "tool_result"
         else "assistant_message" end),
  actor: (if .type == "user" then "user" else "main" end),
  context: {cwd, branch: .gitBranch},
  content: .message.content
}' "$CONV_FILE"

Event Types:

1. user_message: User input to main agent
2. assistant_message: Main agent text output (non-tool)
3. tool_use: Any tool invocation (Edit, Write, Bash, Task, Read)
4. tool_result: Output from tool execution
5. state_transition: Detected task state change (inferred from TodoWrite or task.json)

Phase 3: Classify File Operations

For each Edit/Write tool use, classify the target file and worktree:

# File type classification
classify_file_type() {
  local file_path="$1"
  case "$file_path" in
    */src/main/java/*.java) echo "source_file" ;;
    */src/test/java/*.java) echo "test_file" ;;
    */module-info.java|*/pom.xml|*.gradle) echo "infrastructure" ;;
    *.md|*.txt) echo "documentation" ;;
    *) echo "other" ;;
  esac
}

# Worktree type classification
classify_worktree() {
  local cwd="$1"
  case "$cwd" in
    /workspace/main*) echo "main_worktree" ;;
    /workspace/tasks/*/code) echo "task_worktree" ;;
    /workspace/tasks/*/agents/*/code) echo "agent_worktree" ;;
    *) echo "unknown" ;;
  esac
}

Phase 4: Detect State Transitions

Infer state transitions from conversation:

# Method 1: TodoWrite tool calls mentioning states
jq -r 'select(.type == "assistant") |
  .message.content[]? |
  select(.type == "tool_use" and .name == "TodoWrite") |
  .input.todos[]? |
  select(.content | contains("SYNTHESIS") or contains("IMPLEMENTATION") or contains("VALIDATION"))' \
  "$CONV_FILE"

# Method 2: Infer from working directory changes and Task tool patterns
# INIT → CLASSIFIED: First Task tool invocation
# CLASSIFIED → REQUIREMENTS: Multiple parallel Task tools (review mode)
# REQUIREMENTS → SYNTHESIS: After all agents in review mode complete
# SYNTHESIS → IMPLEMENTATION: CD to task worktree + Task tools (implementation mode)

Phase 5: Extract User Approval Checkpoints

Search for user approvals after critical state transitions:

# Extract user messages and check for approval patterns
jq -c 'select(.type == "user") | {
  timestamp,
  content: .message.content,
  is_approval: (.message.content | test("(?i)(yes|approve|proceed|continue|go ahead|lgtm|looks good)"))
}' "$CONV_FILE"

Phase 6: Collect Current Git and Task State

Gather filesystem state to complement timeline:

# Task state
if [ -f "/workspace/tasks/${TASK_NAME}/task.json" ]; then
  cat "/workspace/tasks/${TASK_NAME}/task.json"
fi

# Git worktrees
git worktree list

# Git branches and merge status
cd /workspace/main
git branch --contains ${TASK_BRANCH_HEAD} 2>/dev/null | grep -q "main" && echo "MERGED" || echo "NOT_MERGED"

# Agent outputs (if applicable)
ls -la "/workspace/tasks/${TASK_NAME}/"*-requirements.md 2>/dev/null || true

Phase 7: Generate Statistics

Compute aggregate statistics:

# Count events by type
# Count tool uses by tool name
# Count state transitions
# Identify agents invoked (Task tool calls)
# Detect approval checkpoints vs required checkpoints

Output Format

Structured Timeline JSON - Comprehensive, queryable data:

{
  "session_metadata": {
    "session_id": "88194cb6-734b-498c-ab5d-ac7c773d8b34",
    "task_name": "implement-formatter-api",
    "start_timestamp": "2025-10-30T14:58:00Z",
    "end_timestamp": "2025-10-30T20:24:59Z",
    "conversation_file": "~/.config/projects/-workspace/88194cb6-....jsonl",
    "conversation_size_bytes": 6046009
  },

  "timeline": [
    {
      "timestamp": "2025-10-30T14:58:00Z",
      "seq": 1,
      "type": "user_message",
      "content": "Work on implement-formatter-api task",
      "context": {
        "cwd": "/workspace/main",
        "branch": "main"
      }
    },
    {
      "timestamp": "2025-10-30T14:58:20Z",
      "seq": 3,
      "type": "tool_use",
      "actor": "main",
      "tool": {
        "name": "Edit",
        "input": {
          "file_path": "/workspace/tasks/.../FormattingRule.java"
        }
      },
      "context": {
        "cwd": "/workspace/tasks/implement-formatter-api/agents/architect/code",
        "branch": "implement-formatter-api-architect"
      },
      "file_classification": {
        "type": "source_file",
        "worktree_type": "agent_worktree",
        "agent": "architect"
      }
    },
    {
      "timestamp": "2025-10-30T15:02:00Z",
      "seq": 5,
      "type": "state_transition",
      "from_state": "SYNTHESIS",
      "to_state": "IMPLEMENTATION",
      "trigger": "main_agent",
      "user_approval_found": false,
      "context": {
        "cwd": "/workspace/tasks/implement-formatter-api/code",
        "branch": "implement-formatter-api"
      }
    }
  ],

  "git_status": {
    "current_branch": "main",
    "branches": [
      {
        "name": "implement-formatter-api",
        "head": "def456",
        "merged_to_main": false,
        "task_complete_but_not_merged": true
      }
    ],
    "worktrees": [
      {
        "path": "/workspace/tasks/implement-formatter-api/code",
        "branch": "implement-formatter-api",
        "head": "def456",
        "pruned": false
      }
    ]
  },

  "task_state": {
    "task_json": {
      "exists": true,
      "path": "/workspace/tasks/implement-formatter-api/task.json",
      "state": "COMPLETE"
    },
    "module_in_main": {
      "exists": false,
      "expected_path": "/workspace/main/formatter"
    },
    "agent_outputs": {
      "architect": {
        "file": "implement-formatter-api-architect-requirements.md",
        "exists": true
      }
    }
  },

  "statistics": {
    "total_events": 150,
    "user_messages": 5,
    "tool_uses": {
      "Edit": 26,
      "Write": 15,
      "Bash": 50,
      "Task": 4,
      "Read": 30
    },
    "state_transitions": 6,
    "agents_invoked": ["architect", "engineer", "formatter"],
    "approval_checkpoints": {
      "after_synthesis": {
        "required": true,
        "found": false,
        "transition_timestamp": "2025-10-30T15:02:00Z"
      }
    }
  }
}

Critical Rules

DO:

• ✅ Parse entire conversation into chronological timeline
• ✅ Include ALL event types (user messages, tool uses, results, state transitions)
• ✅ Preserve working directory and git branch context for every event
• ✅ Classify file operations (source/test/infrastructure/documentation)
• ✅ Classify worktree types (main/task/agent worktrees)
• ✅ Extract user approval patterns
• ✅ Compute aggregate statistics
• ✅ Verify current git and task state
• ✅ Keep timeline comprehensive (any auditor can query it)

DON'T:

• ❌ Filter timeline based on what you think auditors need
• ❌ Pre-compute specific compliance checks (auditors will query timeline)
• ❌ Make judgments about violations (just provide data)
• ❌ Make recommendations (that's auditors' job)
• ❌ Skip events to save tokens (timeline must be complete)
• ❌ Interpret intent or make assumptions

Verification Checklist

Before outputting structured timeline JSON:

• session_metadata section complete with session ID, task name, timestamps
• timeline array contains ALL events in chronological order
• Each timeline event has timestamp, seq, type, context fields
• Tool uses include working directory and git branch context
• File operations classified by type and worktree
• State transitions detected and recorded
• git_status section includes branches, worktrees, merge status
• task_state section includes task.json, module existence, agent outputs
• statistics section includes event counts, tool usage, approval checkpoints
• JSON is valid and parseable
• No compliance judgments included (data only)

Related Skills

• get-history: Access raw conversation logs
• audit-protocol-compliance: Use timeline to check protocol violations
• audit-protocol-efficiency: Use timeline to find efficiency improvements