session-investigator_skill

Overview

This skill inspects fast-agent session and history files to diagnose unexpected session endings, tool loop failures, and sub-agent correlation issues. It helps you locate problematic messages, match tool calls to results, compute LLM and tool timing stats, and identify common failure patterns quickly. Use it to restore valid history, analyze conversation flow, and map sub-agent traces to main sessions.

How this skill works

The skill reads session.json and history_<agent>.json files in .fast-agent/sessions/<session-id>/ and parses message entries, channels, tool_calls, and tool_results. It provides jq-based commands to count messages, view specific entries, correlate tool call/result IDs, aggregate timing metrics for LLM and tools, and locate sub-agent trace files by timing. It also outlines patterns and fixes for common issues like unanswered tool calls and duplicate user messages.

When to use it

• A session ended unexpectedly or an API error mentions missing tool output.
• Debugging tool loops or when an assistant stopped with stop_reason: "toolUse".
• Correlating sub-agent (agent__) traces with the main session for root-cause analysis.
• Measuring LLM call durations and identifying slow or expensive calls.
• Truncating or repairing corrupted session histories to resume a run.

Best practices

• Always back up history files before truncating or editing them.
• Use the correlation ID pattern: assistant.tool_calls → user.tool_results to validate tool loops.
• Rely on fast-agent-timing and fast-agent-tool-timing channels for precise timing and correlation.
• Check rotating history_previous.json files when investigating recent changes or rollbacks.
• Inspect fastagent.jsonl log entries for errors around the session time range.

Example use cases

• Detect a pending tool call: find an assistant message with tool_calls and no subsequent user.tool_results, then truncate to the last valid result.
• Identify slow LLM responses: compute duration_ms per assistant message and list the slowest calls.
• Aggregate tool timings: produce counts, totals, and averages for all tool executions in a session.
• Map sub-agent traces to main session tool calls by matching start_time/end_time monotonic values.
• Uncover duplicate user messages introduced by hooks by scanning consecutive message roles.