Agent session forensics
Skill yeaight7/agent-powerups/skills/agent-session-forensics
Use when diagnosing agent session history, interrupted tool loops, missing tool results, timing bottlenecks, or subagent trace correlation.From its SKILL.md
npx -y skills add yeaight7/agent-powerups --skill agent-session-forensicsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
- runs commandsInstructs the agent to run 6 commands, including `jq 'length' history.json` and 5 more.
SKILL.md
3.1 KB, 649 tokens by cl100k_base, as published. Nobody here has run it
Agent Session Forensics
When To Use
- Agent session ended mid-tool-call or cannot resume.
- Tool call appears in assistant turn but no corresponding result turn follows.
- Need to correlate tool calls, tool results, and timing metadata.
- Diagnosing slow LLM calls, duplicate user turns, or malformed results.
- Debugging experimental MCP data-layer sessions.
Requirements / Checks
- Locate session directory and history files before editing anything.
- Prefer read-only inspection first.
- Have
jqor equivalent JSON tooling available. - Ask before modifying, truncating, or deleting any session or history file.
Workflow
-
Inventory session files — find metadata, current history, rotated previous history, and related subagent histories.
-
Count and list last turns:
jq 'length' history.json # total messages jq '.[-10:] | .[] | {role, stop_reason}' history.json # last 10 turns jq '.[] | select(.role=="assistant") | .tool_calls[].id' history.json # tool call IDs jq '.[] | select(.role=="user") | .tool_results[]?.tool_call_id' history.json # results -
Correlate tool call IDs — every
tool_callin an assistant turn must have a matchingtool_resultin the immediately following user turn. Find the first gap. -
Check timing for slow calls:
jq '.[] | select(.timing) | {role, duration_ms: .timing.duration_ms}' history.json -
Identify failure pattern — see table below.
-
Repair (if approved) — write a backup first (
cp history.json history.json.bak), then make the smallest possible fix at the last valid correlation boundary.
Common Failure Patterns
| Symptom | Likely cause | Repair |
|---|---|---|
| Tool call with no result turn | Session interrupted mid-tool | Truncate after last matched pair |
| Two consecutive user turns | Duplicate message insertion | Remove the duplicate |
tool_result with no prior tool_call | Corrupted or manually edited history | Remove orphan result |
Empty content on assistant turn | Model returned no text + no tools | Usually safe to truncate |
| Session loops without progress | Missing result causes re-prompt | Inject minimal synthetic result |
Safety Constraints
- Do not edit session JSON without backing up the original first.
- Treat history files as sensitive: prompts, tool arguments, credentials, and file contents may appear.
- Do not infer user intent from stale history when current user instructions conflict.
- Do not repair by deleting broad ranges — find the last valid tool-call/result correlation boundary.
Validation / Done Criteria
- Report the names of every session file inspected.
- Every tool-call ID is accounted for (matched or flagged as unmatched).
- Any proposed repair names the backup path and truncation boundary.
- No session file is mutated without explicit user approval.
References
references/history-diagnostics.md
What ships with it: 1 file
1.3 KB alongside SKILL.md
references/
- history-diagnostics.md1.3 KB
Gives 0 of the 12 instructions most context ai engineering skills give in 649 tokens
Counted across 1,328 of the 2,349 authors here whose files we hold, read 2026-09-06
- Dispatch a fresh subagent for each taskin 76 of 1328, across 59 files
- Perform spec compliance review before code quality reviewin 44 of 1328, across 34 files
- Dispatch a final code reviewer after all tasksin 38 of 1328, across 26 files
- Answer subagent questions before allowing implementationin 36 of 1328, across 26 files
- Use the least powerful model capable of the taskin 33 of 1328, across 26 files
- Create a TodoWrite list for all tasksin 32 of 1328, across 22 files
- Perform a task review after each implementationin 31 of 1328, across 24 files
- Extract all tasks and context from the planin 29 of 1328, across 20 files
- Provide full task text to subagentsin 28 of 1328, across 20 files
- Use git worktrees for isolated workspacesin 25 of 1328, across 20 files
- Specify the model explicitly when dispatching a subagentin 23 of 1328, across 18 files
- Execute all tasks from the plan without stoppingin 21 of 1328, across 16 files
Said here and by no other author read
- Locate session directory and history files
- Correlate tool call IDs with tool results
- Identify gaps in tool call sequences
- Check timing metadata for slow calls
- Create a backup before modifying files
- Make the smallest possible fix
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.