用途：分析智能体运行产物，解释单个任务缓慢或失败的原因，并对比两次运行的执行路径差异。数据来源分工明确：pi 会话 JSONL 是执行细节的事实来源，tasks.jsonl 是任务最终状态的事实来源，attempts/<task_id>.json 是重试生命周期的事实来源。指标须经 ego_bench/session_parser.py 计算，skill 脚本只用于过滤、定位证据与呈现。
主要能力：run 级筛选与证据汇总（analyze_run.py）、SessionStats 单行 JSON 投影（session_summary.py）、人类可读概览与错误样本（session_quickscan.py）、工具错误与 assistant stop 错误定位（extract_errors.py）、ToolCall 与结果配对及参数指纹（extract_tool_calls.py）、连续相似调用聚类（retry_clusters.py）、逐轮 think/LLM/env 计时（turn_timings.py）、思考/文本/最终输出提取（extract_outputs.py）、首条提示与最终文本提取（extract_io.py）、两次运行配对差异（runs_pair_diff.py）。
使用方式：先解析项目根与环境，例如 ROOT=$(git rev-parse --show-toplevel)、PY="$ROOT/.venv/bin/python"、SCRIPTS="$ROOT/.claude/skills/pi-session-analyzer/scripts"；再运行 $PY "$SCRIPTS/analyze_run.py" runs/<run_id> --top 5 等命令。需逐行流式读取大会话，不得整体 json.load；缺少依赖应显式报错并指明正确解释器，分析期间不安装依赖。
适用场景：排查工具失败、assistant stopReason=error、运行错误、判定失败、重试与缓慢任务；核对判定争议时查看 judges/<task_id>_judge.json；比较不同运行指标差异。
限制：不修改原始运行产物；attempt_count==1 不代表只运行一次，强制重跑会就地覆盖；旧运行缺少 attempt 产物时只能说明缺乏可靠关联；wait 类失败可能静默返回 false，跨版本工具失败数不可直接比较；搜索运行时错误标记须排除加载 skill 文本的轮次，否则产生规则性误报。