<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->

---
scene: multi_trace_result_comparison
priority: 0
effort: medium
required_capabilities: []
optional_capabilities: []
keywords:
  - 分析结果对比
  - 结果对比
  - 多 Trace 对比
  - 多 trace 对比
  - 多个 Trace 对比
  - 两个 Trace 对比
  - 另一个 Trace
  - 另外一个 Trace
  - analysis result comparison
  - result comparison
  - multi trace comparison
  - compare snapshots
  - compare analysis results
compound_patterns:
  - "对比.*(分析结果|结果|snapshot|另一个\\s*Trace|另外一个\\s*Trace|两个\\s*Trace|多个\\s*Trace|多\\s*Trace)"
  - "(分析结果|结果|snapshot|snapshots).*(对比|compare)"
  - "compare.*(analysis results|snapshots|multi trace|another trace)"

phase_hints:
  - id: result_snapshot_selection
    keywords: ['snapshot', '结果', '候选', 'baseline', 'current result', 'analysis result']
    constraints: '必须先确认要对比的是 AnalysisResultSnapshot，而不是旧的 referenceTraceId raw trace 对比。候选不唯一时必须让用户选择 baseline 和 candidates。'
    critical_tools: []
    critical: true
  - id: matrix_first
    keywords: ['matrix', 'delta', 'metric', 'fps', 'jank', 'startup', '启动', '帧率']
    constraints: '定量结论只能来自 ComparisonMatrix 的 normalized metrics。缺失 metric 要标注 missing reason；只有允许回填时才请求 trace backfill。'
    critical_tools: []
    critical: true

plan_template:
  mandatory_aspects:
    - id: snapshot_scope
      match_keywords: ['snapshot', 'analysis result', '结果', 'baseline', 'candidate']
      suggestion: '分析结果对比必须先确认 snapshot 范围、baseline 和 candidates'
    - id: comparison_matrix
      match_keywords: ['matrix', 'metric', 'delta', 'fps', 'jank', 'startup', '启动', '帧率']
      suggestion: '分析结果对比必须构造 ComparisonMatrix，并基于结构化 metric 输出 delta'
---

#### 分析结果对比（用户提到多个 Trace 的已有分析结果、snapshot、另一个 Trace 结果）

这是新的多窗口/多用户结果快照对比，不是旧的单窗口 `referenceTraceId` 双 Trace raw data 对比。

**核心原则：**
1. 先对比 `AnalysisResultSnapshot`，不默认唤醒原 TraceProcessor。
2. 定量结论只来自 `ComparisonMatrix` 中的 normalized metrics。
3. 不同 scene、设备、包名或采集配置不一致时，结论必须降级并明确说明。
4. 每个关键数值必须能追溯到 snapshot、metric key 和 evidence refs。
5. AI 只能解释差异，不允许从自然语言报告里重新抽取或发明指标。

**Phase 1 — Snapshot 范围确认：**

- 当前窗口已有 latest snapshot 时，把它作为默认 baseline 候选。
- 通过结果目录或候选选择器确认其他可读 snapshot。
- 候选唯一时可以直接发起 comparison；候选不唯一时必须让用户确认。
- baseline 必须明确；不要把“当前 Trace”隐式当成所有场景的 baseline。

**Phase 2 — 构造 ComparisonMatrix：**

- 使用 `multi_trace_result_comparison` Skill contract 描述输入输出边界。
- 构造输入：`snapshot_ids`, `baseline_snapshot_id`, 可选 `metric_keys`, 原始 `query`。
- 默认 metric 范围：`startup.total_ms`, `scrolling.avg_fps`, `scrolling.jank_rate_pct`。
- 用户显式要求某个 metric key 时，优先加入 matrix；缺失时进入缺失矩阵。

**Phase 3 — 缺失与回填：**

- snapshot 已有 metric 时优先使用快照值。
- snapshot 缺少标准 metric，且用户或策略允许回填时，才能回查原 Trace。
- 回填失败时 comparison 仍完成，并把失败原因写入 missing matrix / uncertainty。
- 自定义 metric 没有定义 extractor 时不要硬算，返回不支持或缺失原因。

**Phase 4 — 结论输出：**

输出必须包含：

1. `ComparisonMatrix` delta 表，包含 baseline、candidate 值、delta、deltaPct 和 trend。
2. 显著变化列表，只列出有结构化证据的变化。
3. 不可比/缺失/回填失败说明。
4. AI 解释分为“已验证事实”和“推断”，推断必须基于 matrix 中的事实。

禁止：

- 使用旧 `execute_sql_on("reference")` 路线替代结果快照对比。
- 对单侧缺失 metric 给出百分比变化。
- 用报告正文里的描述覆盖 normalized metric。
