name: failure-analysis
description: 对Agent评测失败案例进行根因分析，准确区分Agent能力问题、样本设计问题、用户模拟器问题和系统问题。当需要分析评测失败原因、归因问题类型、提供改进建议时使用此技能。

失败案例归因分析指南

Overview

对评测失败案例进行根因分析，准确区分问题类型并提供改进建议。核心原则：基于事实证据进行归因，不停留在表面现象。

分析工作流

核心要求

⚠️ 必须逐个分析，禁止批量处理
- 批量只能统计表面现象，无法挖掘根因
- 每个 case 都要完整走完 8 步流程

📄 两层输出文档

1. 归因文档（相同原因聚合）
2. 格式：analysis/{root_cause_type}_{timestamp}.json
3. 相同根因的 cases 写到同一个文档
4. 至少一个 case 的分析过程必须完备（证明分析可信）

5. 遵循 templates/analysis_report_schema.json

6. 总结文档（分析完成后）

7. 格式：analysis/summary_{timestamp}.json
8. 呈现归因类别分布、关键发现

Quick Start

# 1. 读取样本数据
sample = read_json("evaluation_results/xxx.json")

# 2. 按8步流程分析（见下方）- 必须逐个分析

# 3. 使用决策树归因（见 references/decision_tree.md）

# 4. 生成分析报告
analysis_report = {
    "scenario_id": "LA_ST_SICK_LEAVE_001",
    "model": "gpt-4o",
    "failure_summary": "...",
    "analysis": {...},
    "final_state_validation": {...},
    "root_causes": [...],
    "improvements": [...]
}

# 5. 写入归因文档（相同根因聚合）
root_cause_type = "agent_tool_use"  # 根据归因类型命名
output_path = f"analysis/{root_cause_type}_{timestamp}.json"
write_json(output_path, analysis_report)

# 6. 所有分析完成后，写总结文档
summary = {
    "total_cases": 10,
    "root_cause_distribution": {...},
    "key_findings": [...]
}
write_json(f"analysis/summary_{timestamp}.json", summary)

重要：
- ⚠️ 逐个分析，不能批量
- ⚠️ 归因文档按根因类型聚合，至少一个 case 分析完备
- ⚠️ JSON 格式符合 templates/analysis_report_schema.json
- ⚠️ 时间戳格式：YYYYMMDD_HHMMSS

输出格式

文件位置：analysis/{scenario_id}_analysis_{timestamp}.json（相对于工作目录）

命名示例：LA_ST_SICK_LEAVE_001_analysis_20260108_153042.json

JSON Schema：templates/analysis_report_schema.json

必需字段：
- scenario_id - 样本ID
- model - 被评测模型
- evaluation_file - 评测结果文件路径
- failure_summary - 失败简要总结
- analysis - 基础分析（指标、关键轮次、期望vs实际）
- final_state_validation - final_state三层验证
- root_causes - 根因分析（类型、维度、证据、推理）
- improvements - 改进建议（领域、措施、负责方、优先级）

两层失败分析框架

第一层：业务失败原因分析
├── 核心业务目标达成情况
├── 关键业务节点执行状态
├── 业务流程断链位置识别
└── 根本失败原因定位

第二层：过程违规行为分析
├── 信息编造和虚构内容
├── 技术痕迹暴露问题
├── 数据一致性问题
└── 合规控制缺陷

层次关联：业务失败往往伴随违规行为增加，成功率越低的模型通常违规程度越严重。

四类归因分类

Agent能力问题的细分维度

当归因为Agent能力问题时，需要进一步映射到9个核心能力维度：

能力维度归因示例

{
  "root_causes": [
    {
      "type": "Agent能力问题",
      "dimension": ["多轮对话管理", "Prompt遵循"],
      "evidence": [
        "Agent未主动询问用户对活动B的调整需求（轮次3）",
        "BusinessRules明确要求'主动了解清楚用户的调整要求'但Agent未执行"
      ],
      "reasoning": "Agent在识别出多个活动后，应该逐个询问用户期望，但仅被动响应了明确需求，违反了系统prompt的主动引导要求"
    }
  ]
}

8步分析流程

详细流程： references/analysis_workflow.md

三层验证机制

当final_state与expected_state不符时，按以下顺序验证：

验证层1：工具职责边界验证
  └─ 工具应该负责该状态更新?
     ├─ 是但未更新 → 系统问题
     └─ 否 → 进入层2

验证层2：Agent操作完整性验证
  └─ Agent是否遗漏了必要操作?
     ├─ 调用了但未生效 → 系统问题
     ├─ 遗漏了调用 → 进入层3
     └─ 调用参数错误 → Agent能力问题

验证层3：业务规则明确性验证
  └─ BusinessRules是否明确要求该操作?
     ├─ 明确要求但Agent未做 → Agent能力问题
     └─ 未明确要求 → 样本设计问题

详细决策树： references/decision_tree.md

质量快速检查（5项核心）

• [ ] 完整阅读了所有对话内容
• [ ] 结论基于对话事实而非prompt假设
• [ ] 区分了用户实际表达vs设定期望
• [ ] 验证了final_state与Agent操作意图的一致性
• [ ] 每个结论都有明确的事实支撑

完整检查清单： references/quality_checklist.md

Reference Files

优秀案例

分析遇到困难时，加载对应类型的案例学习归因思路：

完整案例索引：examples/README.md（含学习路径和场景对比分析）

关键原则

1. 完整阅读 - 必须从conversation_history第一轮开始逐轮阅读
2. 事实vs假设 - 只能基于对话事实归因，不能基于prompt推断
3. 层次验证 - final_state异常时必须运用三层验证机制
4. 证据链完整 - 每个结论必须有具体证据支撑