Tool Call Diagnose

Leading word: the calls dump — paired toolCall/toolResult records delivered by /skill:tool-call-extract. Every finding cites dump records or trace entry indices (call_entry 306, [307]); a finding with neither is an opinion, not a finding.

The tool under diagnosis is the target tool (subagent, bash, edit, ...). Three axes run as parallel fresh-context sub-agents: 失败分类判责 / 重试浪费 / 用法沉淀. Before any of them runs, one gate decides the whole routing: does a companion skill already exist for this tool?

The gate exists because the recurring real-world outcome is: the agent hit pits that a companion skill already documents (pi-subagents documents exactly why Structured single-child execution cannot be combined with workflowScript fails) — reading it once would have skipped the failure. Findings of that shape route to behavior fixes, not new documentation.

Process

1. Resolve inputs

Target tool name (required, ask if absent) and the trace: either /skill:tool-call-extract deliverables (session file + calls dump + stats), or a session id / symptom the extract skill can resolve. Symptom → filter mapping: "glab api 失败" = bash --args-contains 'glab api' --errors-only; "subagent workflowScript 挂" = subagent --errors-only (narrow with --args-contains workflowScript if noisy).

If no dump in hand, get one from the extract skill's installed script (~/.pi/agent/skills/tool-call-extract/scripts/find-tool-calls.py) — search, triage, then dump. Build two dumps when diagnosing usage or retries: with and without --errors-only (successes and workarounds are evidence). Also build the surrounding-turn trace index:

python3 ~/.pi/agent/skills/skill-call-extract/scripts/find-skill-sessions.py --index <session-file> > trace-index.json