# Replayer Issue 登记表
#
# Postmortem/Regression 过程中发现的问题的结构化追踪。
# 每条记录有唯一 ID (ISS-NNNN)，跨 case 去重。
#
# 目录结构:
#   issues/
#   ├── issues.yaml           # 本文件 — 轻量索引
#   ├── ISS-0021/plan.md      # 详细修复计划（含完整上下文）
#   ├── ISS-0022/plan.md
#   └── ...
#
# 工作流:
#   1. 在 postmortem/regression Phase 7 中，扫描 workspace 对话发现问题
#   2. 读取本文件，检查问题是否已存在（按 title 或 affects 匹配）
#   3. 若已存在：将 case ID 追加到 found_in，按需更新 status
#   4. 若为新问题：分配下一个 ISS-NNNN ID，创建 ISS-NNNN/plan.md 写详细上下文
#
# 字段说明:
#   id:          ISS-NNNN（单调递增）
#   title:       简短描述（去重键 — 相似 title = 同一问题）
#   type:        FLOW | TEMPLATE | KNOWLEDGE | REASONING | CROSS-REF | TOOLING | UX
#   issue_stage: 诊断流水线阶段（ux | template | intake_context | data_retrieval |
#                data_semantics | classification | specialized_diagnosis | recommendation）
#   severity:    P0-critical | P1-high | P2-medium | P3-low
#   status:      open | in_progress | fixed | wontfix
#   affects:     受影响的 {skill, file} 列表，标识需要修改的位置
#   description: 出了什么问题
#   fix_plan:    ISS-NNNN/plan.md 路径（详细）或内联摘要（简单/历史遗留）
#   found_in:    观察到该问题的 case 列表，格式: [{case: TICKET-ID, ws: ws-xxx}]
#   fixed_in:    修复的 commit hash 或 PR 链接

issues:

  # ---------------------------------------------------------------------------
  # 诊断流程缺陷
  # ---------------------------------------------------------------------------

  - id: ISS-0001
    title: 时间窗口判定依赖 Jira 元数据而非指标
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: intake_context
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 用 Jira 创建时间/开始时间作为事件时间锚点，
      应先查询指标找到异常窗口，再验证。
    fix_plan: >
      在 A0 之前增加"基于指标的时间窗口检测"步骤，
      查询 P99 延迟和 QPS 找到实际的异常峰值窗口。
    found_in: [TCOC-5011]

  - id: ISS-0002
    title: 诊断流程中无主动的节点/组件健康检查
    type: FLOW
    severity: P1-high
    status: fixed
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/252
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      检查了指标、TopSQL、SlowQuery，但没有检查组件运行时间/重启次数。
      对基础设施故障（worker 下线、OOM）场景，这是最先出现的信号。
    fix_plan: ISS-0002/plan.md
    found_in:
      - TCOC-5011
      - case: TCOC-5140
        ws: ws-1776646913272-b0d2b9b99
    fixed_in: "current main: collect_evidence now captures component counts, restarts, and worker memory; validated 2026-05-14"

  - id: ISS-0003
    title: Coprocessor worker 不在诊断范围内
    type: KNOWLEDGE
    severity: P1-high
    status: fixed
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      仅将 TiDB、TiKV、PD 作为诊断目标，应包含
      coprocessor TiKV worker、TiFlash 及其他辅助组件。
    fix_plan: >
      已在 collect_evidence.py 中添加 coprocessor worker 指标
      （worker 数量、运行时间、内存）及 --parent-id 支持 Premium 集群路由。
    found_in: [TCOC-5011]
    fixed_in: "afeb49b"

  - id: ISS-0004
    title: 诊断流程中不会自动查询日志
    type: FLOW
    severity: P2-medium
    status: fixed
    issue_stage: data_retrieval
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Loki 日志查询仅在提示时才执行，Error/Fatal 日志提取
      应作为必选步骤。
    fix_plan: >
      日志现已作为 collect_evidence.py 的 A6 段采集，
      SKILL.md Node C 引用日志证据。
    found_in: [TCOC-5011, O11Y-2328599]
    fixed_in: "collect_evidence.py A6"

  - id: ISS-0005
    title: TopSQL 不是诊断流程的必选项
    type: FLOW
    severity: P1-high
    status: fixed
    issue_stage: data_retrieval
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      TopSQL 查询（TiDB 和 TiKV）原为可选项，Agent 在多个 case 中跳过了该步骤，
      导致缺失主要的 CPU 归因信号。
    fix_plan: >
      TopSQL 现已作为 collect_evidence.py A4 段，诊断流程中为必选。
    found_in: [O11Y-2328599, O11Y-2179140]
    fixed_in: "collect_evidence.py A4"

  - id: ISS-0006
    title: TopSQL 查询模板不正确/不完整
    type: TEMPLATE
    severity: P1-high
    status: fixed
    issue_stage: template
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      TopSQL SQL 使用了错误的列名、缺少字段或时间格式不对，
      Agent 不得不猜测列名。
    fix_plan: >
      已在 collect_evidence.py 中使用正确的 clinic-api TopSQL 查询修复。
    found_in: [O11Y-2328599, O11Y-2179140]
    fixed_in: "collect_evidence.py A4"

  - id: ISS-0007
    title: 缺少热点节点下钻决策规则
    type: FLOW
    severity: P2-medium
    status: open
    issue_stage: classification
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      当指标显示某个节点是异常值（单实例 CPU/延迟飙升）时，
      Agent 没有规则去深入该节点的 TopSQL/日志，而是平等对待所有节点。
    fix_plan: >
      在 Node C 增加决策规则：若实例间指标方差较大，
      识别热点实例并聚焦于该实例的 TopSQL/日志下钻分析。
    found_in:
      - O11Y-2328599
      - case: O11Y-2328599
        ws: ws-1776256323680-07f26bb90
      - case: GH-264
        ws: lark-ws-5c83e277-065b-4f29-8c06-033756674f83
      - case: O11Y-2190994
        ws: ws-1774410422679-a81490e96

  - id: ISS-0008
    title: SlowQuery 分析缺少执行计划解析
    type: TEMPLATE
    severity: P1-high
    status: fixed
    issue_stage: template
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      获取了 SlowQuery 但未提取或分析 decoded_plan，
      Agent 无法区分索引扫描和全表扫描。
    fix_plan: >
      collect_evidence.py A3b 现已为 Top 慢查询 digest 获取 decoded_plan。
    found_in: [O11Y-2328599, O11Y-2179140]
    fixed_in: "collect_evidence.py A3b"

  - id: ISS-0009
    title: 缺少跨数据源交叉验证机制
    type: CROSS-REF
    severity: P2-medium
    status: open
    issue_stage: classification
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 仅基于单一数据源得出结论，未与其他源交叉验证
      （如 TopSQL CPU vs 指标 CPU，慢查询时间 vs 指标时间）。
    fix_plan: >
      在 Node D 增加交叉验证检查点：结论前须确认假设至少
      被 2 个独立数据源支持。
    found_in:
      - O11Y-2328599
      - case: O11Y-2328599
        ws: ws-1776256323680-07f26bb90

  - id: ISS-0010
    title: clinic-auth.sh 路径发现浪费大量 tool call
    type: TEMPLATE
    severity: P2-medium
    status: fixed
    issue_stage: template
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 花了 10+ 次 tool call 尝试定位 clinic-auth.sh，
      因为 skill 指令中路径不确定。
    fix_plan: >
      SKILL.md 现已通过 $SKILL_DIR 变量提供确切路径。
    found_in: [O11Y-2328599, O11Y-2179140]
    fixed_in: "SKILL.md Step 0"

  - id: ISS-0011
    title: 仅凭单一信号过早下结论
    type: REASONING
    severity: P2-medium
    status: open
    issue_stage: classification
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 看到一个数据源后就得出根因结论（如"CPU 高所以是 CPU 问题"），
      未收集佐证数据。
    fix_plan: >
      在 Node D 增加推理门控："是否有 >= 2 个数据源的证据支持该结论？"
      若不是，返回继续收集数据。
    found_in:
      - O11Y-2328599
      - case: O11Y-2328599
        ws: ws-1776256323680-07f26bb90

  - id: ISS-0012
    title: 执行计划分析是定性的而非定量的
    type: REASONING
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 用文字描述算子但未提取 actRows/estRows 比值、
      算子代价，或识别执行计划树中的具体瓶颈算子。
    fix_plan: >
      在 Node C/D 增加计划分析指导：提取每个算子的 actRows/estRows
      比值，将比值 > 10x 的算子标记为嫌疑点。
    found_in: [O11Y-2328599]

  - id: ISS-0013
    title: 证据采集后未自动生成结构化摘要
    type: FLOW
    severity: P2-medium
    status: fixed
    issue_stage: data_retrieval
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      采集完所有证据后 Agent 没有汇总视图，
      需重新读取多个文件来综合分析。
    fix_plan: >
      collect_evidence.py 现已输出 evidence_summary_for_agent.txt。
    found_in: [O11Y-2179140]
    fixed_in: "collect_evidence.py"

  - id: ISS-0014
    title: 跨数据源需要时序关联验证
    type: REASONING
    severity: P1-high
    status: open
    issue_stage: classification
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 将问题归因于时间上不匹配的事件，
      如将事件开始后 90 分钟的扩容归为原因。
    fix_plan: >
      增加时序验证步骤：引用某事件作为因果关系时，
      验证其时间戳落在事件窗口内。
    found_in: [TCOC-4964]

  - id: ISS-0015
    title: 建议中混淆诊断查询目标与实际操作目标
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: recommendation
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 建议"在 X 上加索引"，但 X 是诊断查询目标（如 TopSQL）
      而非实际导致问题的用户表。
    fix_plan: >
      增加建议验证：确保建议的表/索引对应实际问题查询，
      而非诊断查询本身。
    found_in: [TCOC-4964]

  - id: ISS-0016
    title: 扩容是缓解措施不是根本解决方案
    type: REASONING
    severity: P2-medium
    status: open
    issue_stage: recommendation
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 建议"扩容 TiKV"作为根因解决方案，但扩容是缓解措施，
      根因修复需要查询优化或配置调优。
    fix_plan: >
      增加推理指导：区分缓解措施（扩容、重启）和根因修复
      （加索引、改配置、改代码），建议应两者都包含。
    found_in: [TCOC-4964]

  - id: ISS-0017
    title: TiDB CPU 高 + GC 异常时需要 heap profile
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      当 TiDB CPU 高且 GC 指标异常时，Agent 应获取持续性能剖析的
      heap profile 以定位内存泄漏或 GC 压力源。
    fix_plan: >
      增加决策规则：若 TiDB CPU > 80% 且 GC duration 升高，
      通过持续性能剖析 API 获取 heap profile。
    found_in: [TCOC-5019]

  - id: ISS-0018
    title: Premium 集群持续性能剖析路由容易出错
    type: KNOWLEDGE
    severity: P1-high
    status: open
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Premium 集群的持续性能剖析 API 需要 parent_id 路由
      （与指标类似），Agent 经常使用错误的集群范围。
    fix_plan: >
      在 SKILL.md 中与 --parent-id 指导一起记录性能剖析 API 路由，
      同一规则：worker/PD/TiKV 组件使用 parent_id。
    found_in: [TCOC-5019]

  - id: ISS-0019
    title: Heap 调用栈应与已知 bug 交叉比对
    type: CROSS-REF
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      当 heap profile 显示特定函数热点时，Agent 应搜索
      已知的 TiDB issue 匹配调用栈模式。
    fix_plan: >
      在 Node D 增加步骤：若性能剖析显示特定函数热点，
      搜索 GitHub issues 查找该函数名 + "memory" 或 "OOM"。
    found_in: [TCOC-5019]

  - id: ISS-0020
    title: 需区分负载触发问题与产品 bug
    type: REASONING
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/253
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 混淆"负载导致了问题"与"产品 bug 导致了问题"，
      需区分：是负载不合理，还是 TiDB 对正常负载的处理有 bug？
    fix_plan: ISS-0020/plan.md
    found_in:
      - TCOC-5019
      - case: TCOC-5140
        ws: ws-1776646913272-b0d2b9b99

  - id: ISS-0024
    title: 诊断输出中缺少 Clinic 深度链接（日志/指标/TopSQL viewer URL）
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/230
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户期望诊断输出中包含 Clinic 日志/指标/TopSQL viewer 的可点击链接，
      如 https://clinic.pingcap.com/clusters/{cluster_id}/logs?query=...&start=...&end=...
      方便用户直接跳转查看原始数据。当前输出仅有文本描述，无深度链接。
    fix_plan: ISS-0024/plan.md
    found_in:
      - case: O11Y-2328599
        ws: ws-1776256323680-07f26bb90

  - id: ISS-0025
    title: Download 文件下载按钮点击无反应、无提示
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    fixed_in: "PR#463"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/231
    affects:
      - skill: investibook-frontend
        file: frontend/components/StudioPanel/FileViewer.tsx
    description: >
      用户点击文件下载按钮后无任何反应，也没有错误提示或 loading 状态反馈。
      可能是下载逻辑静默失败，或按钮的 onClick 事件未正确绑定/触发。
    fix_plan: >
      1. 检查 FileViewer.tsx 中下载按钮的 onClick handler 是否正确触发
      2. 添加 loading 状态和错误提示（下载失败时 toast 通知用户）
      3. 验证下载 API 端点是否正常返回文件内容
    found_in:
      - case: N/A
        ws: ws-1776337653260-0e3440ed7

  - id: ISS-0026
    title: Diagnosis helpful 反馈弹窗缺少 dismiss 按钮
    type: UX
    severity: P3-low
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/232
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      诊断完成后的 "helpful?" 反馈提示没有关闭/dismiss 按钮，
      用户无法主动关闭该提示。
    fix_plan: >
      在 helpful 反馈组件上添加一个小的 X 关闭按钮。
    found_in:
      - case: N/A
        ws: ws-1776402680190-422db7d59
    fixed_in: "PR#286"
    fix_source: autofix

  - id: ISS-0027
    title: Task 执行中只显示 "bash"，不显示具体任务名
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/233
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      Tool call 在执行过程中只显示 "bash" 字样，只有执行成功后
      才显示具体名字（如 "Collect evidence for TiKV hotspot diagnosis"）。
      用户在等待时无法知道当前在做什么。
    fix_plan: >
      Tool call 的 title/description 应在开始执行时就显示，
      而非等到 completed 状态才渲染。检查 SSE tool event 中
      title 字段是否在 running 状态时已传递，前端是否正确渲染。
    found_in:
      - case: N/A
        ws: ws-1776402680190-422db7d59
    fixed_in: "PR#282, PR#284"

  - id: ISS-0028
    title: '"Waiting & Running" 状态标签在回复过程中仍显示'
    type: UX
    severity: P3-low
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/234
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      单个 tool call 的 "Waiting" / "Running" 状态标签只应在
      agent 未开始回复时显示。一旦 agent 开始回复（有 text 输出），
      该状态标签应隐藏，否则信息冗余且容易混淆。
    fix_plan: >
      在 ChatPanel 中检测到 assistant text 开始流式输出后，
      隐藏 tool call 的 Waiting/Running 状态标签。
    found_in:
      - case: N/A
        ws: ws-1776402680190-422db7d59
    fixed_in: "PR#286"
    fix_source: autofix

  - id: ISS-0035
    title: Agent 未区分正常 panic（超时中断）和异常 panic（bug）
    type: KNOWLEDGE
    severity: P1-high
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/243
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 在日志中发现 panic 后直接将其作为异常信号，未判断 panic
      来源。TiDB 中存在多种"正常 panic"模式，如用户请求超时触发的
      "Query execution was interrupted, maximum statement execution time exceeded"
      （executor:3024）。这类 panic 是预期行为，不是 bug。Agent 需要
      已知正常 panic pattern 列表来过滤，避免误报。
    fix_plan: ISS-0035/plan.md
    found_in:
      - case: O11Y-2429368
        ws: lark-ws-3f41b760-4a79-4ce7-b523-ac731d3098ee

  - id: ISS-0036
    title: Loki 日志查询对部分集群返回空结果或 404
    type: TOOLING
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/244
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      Loki 日志查询存在两种失败模式：(1) O11Y-2429368 中返回零结果（error/warn/info 均为 0），
      实际 panic 日志存在；(2) O11Y-2489480（GCP Japan 专有集群）中返回 HTTP 404。
      两者均导致 Agent 无法获取日志，在 panic/pod-restart 场景下无法确认告警根因。
      可能原因：LogQL 查询过严、Loki endpoint URL 构造错误、日志覆盖范围缺失、或区域权限差异。
    fix_plan: ISS-0036/plan.md
    found_in:
      - case: O11Y-2429368
        ws: lark-ws-3f41b760-4a79-4ce7-b523-ac731d3098ee
      - case: O11Y-2489480
        ws: ws-1777512849128-e855d536a

  - id: ISS-0037
    title: Panic 告警诊断应优先查找和分类 panic 日志
    type: FLOW
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/245
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      对 TiDBUnexpectedPanicInRecoverableGoroutine 类型告警，Agent 在 Loki 查询
      返回空后直接转向分析 TiKV CPU 热点，花大量时间在不相关的性能问题上。
      对于 panic 类告警，#1 优先级应该是找到 panic 日志并分类，而非分析
      其他性能指标。若 Loki 查询失败，应扩大时间窗口重试或标注"无法验证"，
      而非直接判定 FAKE ALARM。
    fix_plan: >
      1. 在 SKILL.md Node C 增加告警类型路由规则：panic 类告警 → 优先 Loki 日志
      2. Loki 返回空时，扩大时间窗口（±2h）重试
      3. 重试仍失败时，输出 "无法获取 panic 日志，无法确认告警真伪" 而非 FAKE ALARM
      4. 仅在确认 panic 分类后，再分析相关性能问题作为上下文补充
    found_in:
      - case: O11Y-2429368
        ws: lark-ws-3f41b760-4a79-4ce7-b523-ac731d3098ee

  - id: ISS-0038
    title: Node restart 诊断应验证终止信号后再判定 OOM
    type: FLOW
    severity: P1-high
    status: fixed
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/250
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 看到 TiKV 节点重启后内存从 66-68GB 降至 4-8GB，直接判定 OOM Killed，
      未验证：(1) 进程收到 SIGKILL 还是 SIGTERM；(2) 是否有 OOM killer 日志；
      (3) 内存相对于节点规格（128GiB）仅 51%，属正常范围。
      实际是 K8s 滚动重启（ScaleResourcePool 操作），终止信号为 SIGTERM。
    fix_plan: ISS-0038/plan.md
    found_in:
      - case: TCOC-5140
        ws: ws-1776646913272-b0d2b9b99
      - case: O11Y-2489480
        ws: ws-1777512849128-e855d536a
      - case: GH-449
        ws: ws-1778321106889-ddeccd093
    fixed_in: "current main: restart diagnosis no longer treats memory drop alone as OOM evidence; validated 2026-05-14"

  - id: ISS-0039
    title: Agent 应在 node restart 场景下主动检查 Activity Hub 事件
    type: FLOW
    severity: P1-high
    status: fixed
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/251
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      4 个 TiKV 节点重启，Agent 分析了 metrics/logs/memory/TopSQL 但从未检查
      Activity Hub 中的人工操作记录。根因（ScaleResourcePool 操作）在第 4 轮
      人工干预后才被发现。Activity Hub 应作为 node restart 场景的首要检查项。
    fix_plan: ISS-0039/plan.md
    found_in:
      - case: TCOC-5140
        ws: ws-1776646913272-b0d2b9b99
      - case: GH-449
        ws: ws-1778321106889-ddeccd093
    fixed_in: "current main: collect_evidence includes Activity Hub events for restart scenarios; validated 2026-05-14"

  - id: ISS-0033
    title: Grafana 运营看板改进（时间范围、用户维度、成本、活跃度）
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/240
    affects:
      - skill: investibook-infra
        file: deploy/grafana/dashboards/
    description: >
      运营看板需要多项改进：(1) 时间范围从 24h 改为 7 天；
      (2) 按用户维度的 token 消耗曲线，支持点击查看单用户 7 天趋势；
      (3) 每日美元花费加到看板，不用去 AWS 控制台看；
      (4) active user/session/chat 完成数加 7 天变化趋势；
      (5) feedback 成功率看板（success/failure 数据）。
    fix_plan: >
      1. Grafana 面板右上角 time range 默认改为 Last 7 days
      2. 新增 token by user panel，PromQL 按 user label 聚合
      3. 新增 daily cost panel（从 CloudWatch/billing metrics 拉）
      4. 新增 active users trend panel（7 天 DAU/session/chat count）
      5. 新增 feedback rate panel（feedback_total{result=success/failure}）
    found_in:
      - case: N/A
        ws: ws-1776337653260-0e3440ed7

  - id: ISS-0034
    title: 前端引导用户在诊断结束后点击 feedback 按钮
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/241
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      诊断结束后用户不知道/不愿意点 resolve/not resolve 反馈按钮。
      需要在 UI 上添加引导提示，提升 feedback 收集率。
    fix_plan: >
      1. 诊断 complete 后自动弹出/高亮 feedback 按钮
      2. 添加简短引导文案（如"诊断有帮助吗？请反馈"）
      3. 若用户未操作，3 秒后轻量级 tooltip 提示
    found_in:
      - case: N/A
        ws: ws-1776337653260-0e3440ed7
    fixed_in: "PR#286"
    fix_source: autofix

  - id: ISS-0031
    title: Workspace transfer 后 share 默认关闭
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/238
    affects:
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
    description: >
      通过 transfer 功能转移 workspace 给其他用户后，share 设置
      默认变为关闭状态。用户期望 transfer 后保持原有的 share 状态，
      或者默认开启 share 以便原来的协作者继续访问。
    fix_plan: >
      is_shared / workspace_members 概念已在 PR#473（ec7bb9d）中彻底移除，
      workspace 权限收敛为只读模型，不再有 share 开关，该问题不再适用。
    found_in:
      - case: N/A
        ws: ws-1776422911327-914712e20
    fixed_in: "PR#473"

  - id: ISS-0032
    title: 前端缺少主动拉取截断内容的机制
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/239
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      当 assistant 回复内容过长被截断时，前端没有机制让用户主动触发
      拉取剩余内容。用户看到截断的回复后无法获取完整内容，需要手动
      刷新或重新请求。应提供"加载更多"或自动续拉机制。
    fix_plan: >
      1. 检测 assistant message 是否被截断（SSE 是否正常 complete）
      2. 若截断，在消息底部显示"加载完整内容"按钮
      3. 点击后从后端 messages API 拉取完整消息替换当前截断版本
      4. 或在 SSE 重连后自动补齐截断内容
    found_in:
      - case: N/A
        ws: ws-1776422911327-914712e20
    fixed_in: "PR#283"

  - id: ISS-0030
    title: 前端刷新会导致 chat message 显示丢失
    type: UX
    severity: P1-high
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/236
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/api/chat.py
    description: >
      用户在诊断流式输出过程中刷新浏览器，assistant message 丢失。
      原因是交互式 chat 的 SSE 流不在后端持久化消息——仅前端在
      收到 complete 事件后调用 appendMessagesToAPI。刷新时 React
      state 丢失，后端只有 user message，assistant message 永久丢失。
    fix_plan: ISS-0030/plan.md
    found_in:
      - case: N/A
        ws: ws-1776337653260-0e3440ed7
      - case: O11Y-2426677
        ws: lark-ws-a7da5d80-9dce-456b-b947-627f49eb03df
    fixed_in: "PR#283"

  - id: ISS-0029
    title: 首轮诊断回答耗时过长（164s），需要调查优化
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/235
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
      - skill: investibook-core
        file: backend/investibook/core/acp.py
    description: >
      首轮诊断回答整体花费 164s，用户体验不佳。需要调查耗时分布：
      collect_evidence.py 各段耗时、LLM 推理耗时、API 调用耗时等，
      找出瓶颈并优化（如并行化证据采集、减少不必要的 API 调用、
      缓存已有数据等）。
    fix_plan: >
      1. 在 collect_evidence.py 中添加每段耗时日志，定位最慢环节
      2. 评估哪些 API 调用可以并行化（如 TopSQL + SlowQuery 同时查询）
      3. 检查是否有重复/浪费的 tool call（如多次重试同一查询）
      4. 考虑对已采集数据做缓存，避免重复拉取
    found_in:
      - case: N/A
        ws: ws-1776404680608-7eac75cac

  # ---------------------------------------------------------------------------
  # 工具/平台问题
  # ---------------------------------------------------------------------------

  - id: ISS-0021
    title: Jira search-issues API 返回 HTTP 410（v2 已废弃）
    type: TOOLING
    severity: P1-high
    status: fixed
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/211
    affects:
      - skill: jira
        file: .opencode/skills/builtin/jira/scripts/jira_api.py
    description: >
      jira_api.py 使用 /rest/api/2/search，Atlassian 已废弃该端点
      （HTTP 410），需迁移到 POST /rest/api/3/search/jql。
    fix_plan: ISS-0021/plan.md
    found_in:
      - case: O11Y-2392287
        ws: ws-1776139348995-a7101b3a3
    fixed_in: "current main: Jira search helper uses POST /rest/api/3/search/jql; validated 2026-05-14"

  - id: ISS-0022
    title: Jira v3 响应需在 POST body 中显式指定 fields
    type: TOOLING
    severity: P1-high
    status: fixed
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/223
    affects:
      - skill: jira
        file: .opencode/skills/builtin/jira/scripts/jira_api.py
    description: >
      /rest/api/3/search/jql 默认只返回 id，key、summary、
      created 等必须在 body 的 "fields" 数组中显式请求。
    fix_plan: ISS-0022/plan.md
    found_in:
      - case: O11Y-2392287
        ws: ws-1776139348995-a7101b3a3
    fixed_in: "current main: Jira v3 search fields are passed in the POST body; validated 2026-05-14"

  - id: ISS-0023
    title: 自动诊断在无用户指令时触发
    type: FLOW
    severity: P1-high
    status: fixed
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/224
    affects:
      - skill: investibook-core
        file: backend/investibook/core/acp.py
    description: >
      工作区在 Jira source 数据就绪后自动触发诊断流程，
      用户未发送任何消息。用户明确表示"不需要自动触发诊断行为"。
      自动诊断导致用户困惑，且后续用户提问时 agent 上下文已被
      自动诊断占用。此外自动诊断输出未被 messages API 捕获，
      导致 postmortem/regression 无法评估。
    fix_plan: ISS-0023/plan.md
    found_in:
      - case: O11Y-2392287
        ws: ws-1776139348995-a7101b3a3
    fixed_in: "current main: normal Add Source flow no longer unconditionally starts diagnosis; alert-ingestion auto_questions remains an explicit automation path"

  - id: ISS-0040
    title: 支持用户配置自己的 GitHub token
    type: UX
    severity: P2-medium
    status: in_progress
    issue_stage: ux
    fixed_in: "PR#464"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/254
    affects:
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
      - skill: investibook-frontend
        file: frontend/components/SourcesPanel/
    description: >
      用户希望能在 Investibook 中配置自己的 GitHub token，
      以便 agent 在诊断过程中使用用户提供的 token 访问 GitHub API
      （如搜索已知 bug、获取 issue 详情等），而非依赖系统级 token。
    fix_plan: >
      1. 后端：在 workspace 或 user settings 中增加 github_token 字段存储
      2. 前端：在 Settings 页面增加 GitHub token 配置入口
      3. Agent 调用 GitHub API 时优先使用用户配置的 token，fallback 到系统 token
    found_in:
      - case: N/A
        ws: ws-1776337653260-0e3440ed7

  - id: ISS-0041
    title: Agent 缺乏 TiDB 常见使用模式知识（prepare:exec:close=1:1:1 模式下 plan cache hit=0 是正常的）
    type: KNOWLEDGE
    severity: P1-high
    status: open
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/255
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 看到 plan cache hit=0 就认为 plan cache 有问题，方向往 plan cache 推进。
      但在 prepare:exec:close=1:1:1 模式（每次 prepare 只执行一次就 close）下，
      plan cache hit=0 是预期行为——没有可复用的 plan。Agent 需要识别 TiDB 常见
      使用模式：prepare-once-execute-once vs prepare-once-execute-many，前者下
      plan cache 不会命中是正常的。
    fix_plan: >
      在 SKILL.md 增加 plan cache 分析前置检查：
      1. 查 StmtPrepare:StmtExecute:StmtClose 比值
      2. 若 ≈1:1:1 → prepare-once-execute-once 模式，plan cache hit=0 正常
      3. 若 Prepare << Execute → prepare-once-execute-many 模式，plan cache 应有命中
      4. 仅在模式 3 且 hit=0 时才诊断 plan cache 问题
    found_in:
      - case: GH-229
        ws: ws-1775617251254-23027ac1f

  - id: ISS-0042
    title: A/B 对比分析中未验证"嫌疑指标是否真的在两天间有变化"
    type: REASONING
    severity: P1-high
    status: open
    issue_stage: classification
    github_issue: https://github.com/tidbcloud/investibook/issues/256
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 发现某指标"看起来不好"（plan cache miss=100%）就归因为根因，
      但未检查该指标在基线（对照日）是否也一样。在 GH-229 中，plan cache
      miss 在 4/7 和 4/8 两天均为 99.6%——两天一样，不是导致 CPU 变化的原因。
      真正的差异是节点数量从 27 减到 18。
    fix_plan: >
      在 SKILL.md Node D 增加 A/B 推理规则：
      1. 对任何被归因为根因的指标，必须对比问题期 vs 基线期
      2. 若两者无显著差异，该指标是"常量"而非"变量"，不是本次变化的根因
      3. 寻找在两个期间有显著差异的指标作为真正的差异因子
    found_in:
      - case: GH-229
        ws: ws-1775617251254-23027ac1f

  - id: ISS-0043
    title: Expensive Query 告警应优先查 TiDB slow query 日志而非 TopSQL
    type: FLOW
    severity: P2-medium
    status: fixed
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/257
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      对 expensive query 告警（查询超时超过阈值），Agent 使用 TopSQL 作为主要数据源
      找问题 SQL。正确方法应优先查 TiDB slow_query 日志（按 query_time 过滤），
      因为这是该告警类型最直接的证据源。此外应过滤掉 ANALYZE 相关查询，
      因为它们是内部运维操作而非用户负载。
    fix_plan: ISS-0043/plan.md
    found_in:
      - case: O11Y-2426677
        ws: lark-ws-a7da5d80-9dce-456b-b947-627f49eb03df
      - case: GH-264
        ws: lark-ws-5c83e277-065b-4f29-8c06-033756674f83
    fixed_in: "current main: expensive-query evaluation uses Slow Query and plan evidence before TopSQL attribution; validated 2026-05-14"

  - id: ISS-0044
    title: TopSQL 多热点 SQL 排序缺少热点节点关联规则
    type: REASONING
    severity: P1-high
    status: fixed
    issue_stage: classification
    github_issue: https://github.com/tidbcloud/investibook/issues/270
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      当 TopSQL 返回多个热点 SQL 分布在不同节点时，Agent 缺少明确规则将热点节点
      与对应 SQL 关联。GH-264 中 WS-A 看到 db-tikv-67/74 是热点节点（CPU 90%/77%），
      但将问题归因于 db-tikv-30 上的 dh_message_setting（cpu_pct=65.4%），
      而非 db-tikv-67/74 上的 dh_account_basic。正确做法：先识别热点节点，
      再筛选该节点上的 TopSQL 排名，而非在全局 TopSQL 中挑 cpu_pct 最高的。
    fix_plan: ISS-0044/plan.md
    found_in:
      - case: GH-264
        ws: lark-ws-5c83e277-065b-4f29-8c06-033756674f83
    fixed_in: "current main: collect_evidence uses hotspot-instance-scoped TopSQL for attribution; validated 2026-05-14"

  - id: ISS-0045
    title: 同一 ticket 多次诊断结果不一致（非确定性）
    type: REASONING
    severity: P2-medium
    status: open
    issue_stage: classification
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      同一个 O11Y-2426677 ticket 在两个独立 Lark bot session 中被诊断出不同结论。
      WS-B 正确（缺索引），WS-A 错误（归因到其他 SQL）。非确定性的根源是
      TopSQL 排序缺少确定性规则（ISS-0044），但用户信任角度这是独立问题——
      用户期望相同输入产生相同诊断。需要确保诊断流程的关键决策点有确定性规则。
    fix_plan: >
      1. 修复 ISS-0044（热点节点关联规则）可消除本 case 的非确定性根源
      2. 长期：在 SKILL.md 中为所有决策分支定义确定性优先级规则，
         减少 LLM 自由发挥空间导致的结果波动
    found_in:
      - case: GH-264
        ws: lark-ws-5c83e277-065b-4f29-8c06-033756674f83
      - case: GH-479
        ws: ws-1778309256713-a871feaf0

  - id: ISS-0046
    title: 对话结束后显示 "failed Stopped with error" 标记但实际无错误
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/290
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      用户报告 agent 回答结束后出现 "failed Stopped with error" 标记，
      但对话内容完全正常（所有消息 status=completed，无 error 字段）。
      后端持久化数据中无错误记录，问题出在前端渲染逻辑——可能是 SSE 流
      断开时（正常结束或超时）被前端误判为错误状态并显示了错误标记。
    fix_plan: >
      1. 检查前端 SSE 断开处理逻辑，区分正常 complete 和异常断开
      2. 仅在后端返回 error event 或 HTTP 非 2xx 时显示错误标记
      3. 检查是否有 timeout 或 AbortController 触发了 false error state
    found_in:
      - case: TCOC-5156
        ws: ws-1776914177180-90779113b
    fixed_in: "PR#292"

  - id: ISS-0047
    title: Feedback 按钮应与 /issue 命令联动，failed feedback 自动触发 postmortem
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    fixed_in: "PR#292"
    github_issue: https://github.com/tidbcloud/investibook/issues/291
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/api/chat.py
    description: >
      用户期望点击 feedback failed 按钮后能自动触发 /issue 命令，
      将用户的反馈内容作为 issue 提交，并自动对该 workspace 执行 postmortem。
      当前 feedback 和 /issue 是两个独立功能，feedback 结果未被进一步利用。
    fix_plan: >
      1. 在 feedback failed 按钮的 onClick 中增加确认弹窗：
         "是否将此反馈提交为 issue？"
      2. 确认后调用 /issue API，将 feedback 内容 + workspace URL 作为 issue body
      3. 后端 /issue handler 创建 GitHub issue 后，可选触发 replayer postmortem
      4. 考虑在 feedback 成功时也记录，用于统计诊断质量
    found_in:
      - case: N/A
        ws: ws-1776748917691-a6c4270fe

  - id: ISS-0048
    title: '"Failed Stopped with error" 错误标记在 PR#292 修复后再次出现'
    type: UX
    severity: P1-high
    status: fixed
    issue_stage: ux
    fixed_in: "PR#462"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/325
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      用户报告 PR#292 修复后 "Failed Stopped with error" 标记再次出现（O11Y-2447701 workspace）。
      原 ISS-0046 修复仅处理了 SSE 正常结束的误判，但仍有路径（如网络超时、AbortController、
      某些后端响应格式）可能触发错误状态。需要更全面地审查 SSE 断开处理逻辑。
    fix_plan: >
      1. 拉取 O11Y-2447701 workspace（ws-1777282586294-ee253309b）的会话记录
      2. 确认错误触发路径：是 SSE 流超时、服务端主动断开、还是前端 AbortController
      3. 对照 PR#292 的修复逻辑，补全其他未覆盖的断开场景
      4. 添加回归测试：模拟各种断开方式，确保均不显示 false error
    found_in:
      - case: O11Y-2447701
        ws: ws-1777282586294-ee253309b

  - id: ISS-0049
    title: Chat 输入框支持上传图片/文件（Grafana 截图、附件）
    type: UX
    severity: P2-medium
    status: in_progress
    issue_stage: ux
    fixed_in: "PR#466"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/326
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/api/chat.py
    description: >
      用户希望在 chat 输入框中能上传图片（主要是 Grafana 截图）和文件（如日志、配置文件）
      以便交互时直接传递视觉信息给 agent。当前输入框仅支持纯文本输入。
      两个独立用户分别报告：(1) 支持 chat 输入上传图片（#309），
      (2) 对话框支持上传文件到指定位置（#317）。
    fix_plan: >
      1. 前端：在 ChatPanel 输入框添加文件上传按钮（支持图片/PDF/文本）
      2. 后端：扩展 /api/chat/stream 支持 multipart 或 base64 附件
      3. Agent：将图片以 vision 方式传给 Claude，文件以 attachment 附加到 context
      4. 考虑大文件限制（>5MB 提示压缩或拒绝）
    found_in:
      - case: N/A
        ws: ws-1777282586294-ee253309b
      - case: N/A
        ws: ws-1777255034860-77c246876

  - id: ISS-0050
    title: 诊断结论支持一键复制或格式化写入 Jira
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    fixed_in: "PR#459"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/327
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
    description: >
      用户希望最终诊断结论能格式化后写入 Jira（当前阶段先支持复制即可）。
      当前 agent 输出是 Markdown 格式但无方便的"复制"或"导出到 Jira"按钮，
      用户需要手动选中文本复制，体验较差。
    fix_plan: >
      1. 短期：在诊断结论消息底部添加"复制为 Markdown"和"复制为纯文本"按钮
      2. 中期：添加"写入 Jira"按钮，将结论格式化为 Jira comment 格式并通过 Jira API 写入
      3. 需要 workspace 关联的 Jira ticket ID（jira_issue source 已有）
    found_in:
      - case: N/A
        ws: ws-1777255034860-77c246876

  - id: ISS-0051
    title: Workspace 诊断结果中存在时区显示/处理问题
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/328
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户在两个 workspace 中发现时区问题：ws-1776321067358-5907eb6f7 和
      ws-1776387178325-79eef67b7。具体表现未说明，可能包括：
      (1) agent 引用指标时间时未说明时区（UTC vs CST）；
      (2) 前端时间显示未做用户本地时区转换；
      (3) Clinic API 返回 UTC 时间但 agent 直接引用造成混淆。
      需要拉取两个 workspace 的对话记录分析具体表现。
    fix_plan: >
      1. 拉取 ws-1776321067358-5907eb6f7 和 ws-1776387178325-79eef67b7 对话记录
      2. 确认时区问题的具体表现（是 agent 输出、前端显示、还是 API 数据）
      3. 若是 agent 输出：在 SKILL.md 中要求时间均以 UTC+8 (CST) 输出并标注时区
      4. 若是前端显示：在 ChatPanel 渲染时间时统一转换为用户本地时区
    found_in:
      - case: N/A
        ws: ws-1777255034860-77c246876
      - case: GH-448
        ws: ws-1778321106889-ddeccd093

  - id: ISS-0052
    title: 诊断能力增强：接入 Nutshell 管控面代码诊断 skill
    type: FLOW
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/329
    affects:
      - skill: investibook-core
        file: agentkit/skills/
    description: >
      用户希望接入 Nutshell 中的管控面代码诊断 skill，增强 Investibook 的诊断能力。
      Nutshell 是 TiDB Cloud 管控面系统，接入该 skill 后 agent 可在诊断过程中
      查阅管控面代码逻辑（如扩缩容、备份、变配操作）辅助根因分析。
    fix_plan: >
      1. 了解 Nutshell 代码诊断 skill 的接口和能力范围
      2. 评估接入方式：内置 skill / 外部 API
      3. 在 AGENTKIT_SKILLS_DIR 中添加对应 skill 定义
      4. 在 workspace 默认 skill 列表中添加 Nutshell 能力
    found_in:
      - case: N/A
        ws: ws-1776748917691-a6c4270fe

  - id: ISS-0056
    title: Activity Hub 事件 API 对部分集群返回 HTML "Access Denied" 而非 JSON
    type: TOOLING
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/368
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      在 O11Y-2489480（GCP Japan 专有集群）诊断中，查询 Activity Hub 集群事件时，
      API 返回 HTML "Access Denied" 页面而非 JSON 数据，导致无法确认 K8s OOM Kill
      是否为 TiDB Pod 重启的真正原因。同一问题可能影响所有 GCP Japan 区域 Dedicated
      集群的事件查询，导致 collect_evidence.py 中 A5 (events) 段静默失败。
    fix_plan: ISS-0056/plan.md
    found_in:
      - case: O11Y-2489480
        ws: ws-1777512849128-e855d536a

  - id: ISS-0053
    title: 支持按 Use Case 自定义欢迎消息和 Workspace 引导语
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/335
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
    description: >
      用户希望能为不同 Use Case（如性能诊断、故障排查、成本分析等）配置不同的
      欢迎消息和 Workspace 引导语，以便让 Investibook 在不同场景下有更明确的
      使用提示。当前欢迎消息和引导语为全局固定内容，无法按场景定制。
      需求来源：FRM-3781（https://tidb.atlassian.net/browse/FRM-3781）。
    fix_plan: >
      1. 后端：在 workspace 或 system config 中增加 use_case 枚举字段（如 perf_diagnosis/incident/cost）
      2. 后端：为每个 use_case 配置对应的 welcome_message 和 guidance_text 模板
      3. 前端：在 ChatPanel 首次渲染时读取 workspace.use_case，显示对应欢迎消息
      4. 前端（可选）：在 workspace 创建页添加 Use Case 选择入口
      5. 对齐 FRM-3781 需求的具体交互设计后再实现
    found_in:
      - case: N/A
        ws: ws-1777255034860-77c246876

  - id: ISS-0054
    title: Studio 面板内容应按 Ticket Workspace 自定义（FRM-3782）
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/342
    affects:
      - skill: investibook-frontend
        file: frontend/components/StudioPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
    description: >
      用户反馈 Studio 面板内容应支持按 Ticket Workspace 自定义，而非全局固定展示。
      对于不同类型的 ticket workspace（如性能诊断、故障排查），Studio 面板中展示的
      工具、快捷操作、默认视图应有所不同，以提升使用效率。
      需求来源：FRM-3782（https://tidb.atlassian.net/browse/FRM-3782）。
      注意：与 ISS-0053（FRM-3781，自定义欢迎消息）是不同需求，本条关注 Studio 内容。
    fix_plan: >
      1. 后端：在 workspace schema 中增加 studio_config 字段，支持按 workspace 类型配置 Studio 内容
      2. 前端：在 StudioPanel 首次渲染时读取 workspace.studio_config，动态展示对应内容
      3. 对齐 FRM-3782 需求的具体交互设计（工具列表、默认视图、快捷操作）后再实现
    found_in:
      - case: N/A
        ws: ws-1777255034860-77c246876

  - id: ISS-0055
    title: Metrics channel label 对 CLI 用户误标为 web（JWT 无 channel 标记）
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    fixed_in: "PR#498"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/343
    affects:
      - skill: investibook-core
        file: backend/investibook/api/auth.py
      - skill: investibook-infra
        file: deploy/grafana/dashboards/
    description: >
      CLI 用户通过 ib_xxx token 获取 JWT 后，该 JWT 与 web 登录 JWT 格式相同，
      导致 metrics 中的 channel label 将 CLI 用户误标记为 web。
      JWT 过期时间很长，已有 token 难以快速区分。
      用户建议：旧 JWT 用 user-agent 判断 channel，新 JWT 在 payload 中增加 channel 字段
      （ib_ token 登录 → channel=cli，auth0/password 登录 → channel=web）。
    fix_plan: >
      1. 新 JWT：在 token payload 中增加 channel 字段（cli/web），
         ib_xxx token 登录时设为 cli，auth0/password 登录时设为 web
      2. 旧 JWT（无 channel 字段）：在 metrics 采集处通过 user-agent 判断 channel
         （CLI 工具有固定 user-agent 标识）
      3. Grafana/metrics：在 channel label 采集逻辑中优先读取 JWT channel 字段，
         fallback 到 user-agent 判断
      4. 验证：cli 用户的 channel label 正确显示为 cli，不再误标为 web
    found_in:
      - case: O11Y-2379756
        ws: ws-1776085564797-115a18d79

  - id: ISS-0070
    title: Agent 无法访问 TCMS 数据（tcms.pingcap.net 无 skill/工具支持）
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/431
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户报告 Investibook 对 tcms.pingcap.net 支持差。TCMS（TiDB Cloud Management System）
      是 PingCAP 内部的测试/执行管理平台，包含执行计划、测试结果等诊断相关数据。
      Agent 在诊断过程中无法访问 TCMS 数据，导致对依赖 TCMS 指标的问题无法完整分析。
      需要评估是否需要新增 TCMS skill 或在现有 skill 中增加 TCMS API 调用支持。
    fix_plan: >
      1. 了解 TCMS API 接口及认证方式（tcms.pingcap.net API 文档）
      2. 评估哪些 TCMS 数据对诊断有价值（执行计划、测试结果、资源使用等）
      3. 在 agentkit/skills/ 中创建 tcms skill 或在 tidb-clinic-diagnosis SKILL.md 中
         增加 TCMS 数据访问步骤
      4. 配置认证凭据（TCMS token 存入 backend 环境变量或 skill secrets）
    found_in:
      - case: N/A
        ws: ws-1778224419713-8f42da22d

  - id: ISS-0071
    title: Agent 无法访问 clinic.pingcap.com.cn（中国区 Clinic 端点）
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/432
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      用户报告 Investibook 对 clinic.pingcap.com.cn 支持差。clinic.pingcap.com.cn 是
      中国区 Clinic 服务端点，与全球区 clinic.pingcap.com 不同。
      collect_evidence.py 中 clinic-auth.sh 及 API 调用目前使用全球区端点，
      对于中国区集群（使用 clinic.pingcap.com.cn）无法正常认证和查询数据。
      这导致所有使用中国区 Clinic 的集群诊断均会失败。
    fix_plan: >
      1. 检查 clinic-auth.sh 和 collect_evidence.py 中硬编码的 Clinic 域名
      2. 根据集群所在区域（从 Jira source 或集群 ID 判断）动态选择端点：
         - 中国区集群 → clinic.pingcap.com.cn
         - 全球区集群 → clinic.pingcap.com
      3. 确认中国区 Clinic 的认证方式与全球区是否相同（token 格式、auth API 路径）
      4. 在 SKILL.md 中记录区域判断规则，并在 collect_evidence.py 中传入正确端点参数
    found_in:
      - case: N/A
        ws: ws-1778224419713-8f42da22d

  - id: ISS-0057
    title: TopSQL 数据对部分集群不可用（Delta Lake 路径不存在）
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/370
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      collect_evidence.py A4 段查询 TopSQL 时，部分集群返回 HTTP 500，原因是 Clinic
      的 Delta Lake 路径不存在（gs://o11y-prod-shared-asia-northeast1/deltalake/...
      is not a valid path for a Delta Lake table）。目前 Agent 在 evidence_summary
      的 errors 字段中记录了错误，但诊断输出中没有明确提示用户"TopSQL 不可用"。
      用户和 --check 脚本都会将此标记为 TopSQL 缺失，但实际是数据管道问题而非 Agent
      流程问题。需要在诊断输出中区分"TopSQL 未查询"和"TopSQL 查询失败（数据不可用）"。
    fix_plan: ISS-0057/plan.md
    found_in:
      - case: O11Y-2489480
        ws: ws-1777512849128-e855d536a
      - case: TCID-12692
        ws: ws-1778810697094-1dff52c74
      - case: TCID-12704
        ws: ws-1779156165000-34f5ef8b3
      - case: TCOC-5382
        ws: ws-1781054808089-764584b34
      - case: O11Y-2612493
        ws: ws-1783591129535-db196fe8d
      - case: TCID-12948
        ws: ws-1784858772091-b5f9b6847

  - id: ISS-0058
    title: Loki 手动查询脚本输出非纯 JSON 导致 JSONDecodeError（Extra data）
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/373
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      Agent 在 collect_evidence.py 采集后手动执行 Loki 日志查询时，脚本输出了
      非纯 JSON 内容（如多行输出、前缀文本），导致 json.loads() 抛出
      JSONDecodeError: Extra data: line 1 column 5 (char 4)。工具 status=failed，
      Agent 通过第二次重试的 Loki 查询绕过了该问题，但增加了不必要的 tool call。
      O11Y-2489480 中 db-tidb-76 的首次 Loki 查询因此失败。
    fix_plan: >
      1. 检查 collect_evidence.py 手动 Loki 查询脚本的输出格式，确保 stdout 输出单一 JSON 对象
      2. 将调试信息/警告移至 stderr，避免污染 JSON stdout
      3. 若 Loki 返回空结果，统一输出 {"logs": [], "count": 0} 而非 null 或空字符串
      4. 增加 try/except JSONDecodeError 包裹，捕获时输出结构化错误信息
    found_in:
      - case: O11Y-2489480
        ws: ws-1777512849128-e855d536a

  - id: ISS-0063
    title: Agent 未将 CPU% 指标归一化到实际 vCPU 配额
    type: REASONING
    severity: P1-high
    status: fixed
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/399
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      Agent 看到 CPU 从 70% 上升到 100% 就判断为 CPU 瓶颈，未考虑集群实际 vCPU 配额。
      TiDB Cloud 中 CPU% 指标满值为 vCPU×100%（如 8 vCPU 实例满载 = 800%），
      100% 实际仅为 12.5% 负载。用户多轮纠正仍反复出错，Agent 缺乏 CPU 归一化知识。
    fix_plan: ISS-0063/plan.md
    found_in:
      - case: TCOC-5207
        ws: ws-1778028682864-3efd1046a
    fixed_in: "current main: evidence collection records CPU quota/maxprocs and uses normalized utilization for saturation judgment; validated 2026-05-14"

  - id: ISS-0059
    title: Agent 诊断过程中无法提供 Grafana 内部看板链接
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/394
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户要求 agent 提供"确切的 Grafana 链接"来查看相关指标。
      Agent 无法生成指向内部 Grafana 看板的直接链接（需要内部 Grafana 域名、
      dashboard UID 及查询参数），只能描述指标而无法提供可点击的跳转链接。
      与 ISS-0024（Clinic 深度链接）类似，但针对 Grafana 内部监控系统。
    fix_plan: >
      1. 调研内部 Grafana 链接格式（域名、dashboard path、时间范围参数）
      2. 若 Grafana 链接可从集群 ID 和时间窗口构造，在 SKILL.md 中文档化 URL 模板
      3. 在诊断结论中为每个引用的指标提供对应的 Grafana 深度链接
      4. 若 Grafana 需要 VPN/内网访问无法直接提供，则明确告知用户并提供查询路径
    found_in:
      - case: TCOC-5207
        ws: ws-1778028682864-3efd1046a
      - case: O11Y-2581453
        ws: ws-1780545125287-e5d2aefe0

  - id: ISS-0060
    title: Agent 忽略用户在对话中提供的 Clinic URL 及其参数
    type: REASONING
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/395
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      用户在对话开始时提供了含有 clusterId/orgId/projectId 等完整参数的 Clinic URL，
      但 agent 在后续诊断中未解析该 URL 并利用其参数。导致后续查询时重新查找集群信息，
      引发用户抱怨"Didn't I give you the URL at first?"。Clinic URL 包含完整的
      clusterId、deployType、version、region 等，是最直接的集群标识来源。
    fix_plan: ISS-0060/plan.md
    found_in:
      - case: N/A
        ws: ws-1778030624057-6fb0878b4

  - id: ISS-0061
    title: Lark bot 无法读取转发的合并消息
    type: TOOLING
    severity: P2-medium
    status: fixed
    issue_stage: intake_context
    fixed_in: "PR#461"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/396
    affects:
      - skill: investibook-lark
        file: backend/investibook/api/lark.py
    description: >
      用户报告 Lark bot 无法读取用户转发的合并消息（forwarded merged messages）。
      在 Lark 中，合并转发的消息是一种特殊消息类型（msg_type=merge_forward），
      包含多条嵌套消息。当用户将多条消息合并转发给 bot 时，bot 无法解析该类型，
      导致无法获取消息内容进行诊断。
    fix_plan: >
      1. 确认 Lark Webhook handler 中 merge_forward 消息类型的数据格式
      2. 在 lark.py 中增加 merge_forward 消息类型的解析逻辑，
         展开嵌套消息列表并提取各消息文本
      3. 将展开后的消息拼接后传给 agent 上下文
      4. 添加测试用例覆盖 merge_forward 场景
    found_in:
      - case: N/A
        ws: lark-ws-b5adfac1-9e2f-4c5e-895b-359710ef2774

  - id: ISS-0062
    title: Chat 输入框缺少 Slash Command 功能发现引导
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    fixed_in: "PR#458"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/397
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      用户在使用一段时间后才偶然发现 Investibook 支持 slash command（如 /issue、/feedback），
      认为"UI需要提醒一下"。输入框没有任何提示表明支持 slash command，
      缺少功能发现性设计（输入 "/" 时无自动补全、placeholder 无提示）。
    fix_plan: ISS-0062/plan.md
    found_in:
      - case: N/A
        ws: ws-1776767023329-cc9c290b8

  - id: ISS-0064
    title: collect_evidence 脚本默认执行失败（无 cluster_id / 环境未配置）
    type: TOOLING
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/400
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      用户报告 collect_evidence 脚本"默认没成功"。可能原因：(1) 未提供 cluster_id 参数时
      脚本无明确的错误提示；(2) clinic-auth.sh 认证失败但脚本继续执行；
      (3) 环境变量（CLINIC_HOST、SKILL_DIR 等）未设置时脚本静默失败；
      (4) 脚本依赖的上游数据（如 Jira source 准备未完成）不存在时没有友好提示。
      workspace ws-1777542045102-615a34f8a 无 Jira 关联 ticket，可能是该场景触发。
    fix_plan: >
      1. 在 collect_evidence.py 开头增加参数校验：cluster_id 必填，缺失时立即报错退出
      2. 认证失败（clinic-auth.sh 非零退出）时，脚本应立即报告认证失败原因，不继续执行
      3. 关键环境变量缺失时，输出明确的 actionable 错误信息（而非静默失败或 Python traceback）
      4. 拉取 ws-1777542045102-615a34f8a 对话记录分析具体失败原因后补充修复细节
    found_in:
      - case: N/A
        ws: ws-1777542045102-615a34f8a

  - id: ISS-0065
    title: Agent 无法识别通过 UI "Add Sources" 添加的 Jira ticket 并进行诊断
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/401
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
    description: >
      用户通过点击 UI 的"Add Sources"按钮手动添加 Jira ticket 作为 source 后，
      agent 在对话中无法识别该 source 并执行诊断（O11Y-2484314 案例）。
      可能原因：(1) 手动添加的 source 状态（loading/ready）与自动创建的不一致；
      (2) 诊断 SKILL 未从 workspace sources API 动态读取 Jira issue ID，
      而是依赖固定格式的用户消息提供；(3) source 准备（prepare）未自动触发。
    fix_plan: >
      1. 检查 ws-1777453881076-b4724cc4b 对话记录确认具体失败模式
      2. 确认手动添加的 Jira source 准备状态（sources API 返回的 status 字段）
      3. 若是 source 未触发 prepare：在 UI 添加 source 后自动调用 /api/sources/prepare
      4. 若是 SKILL 未读取 sources：在诊断开始时查询 workspace sources API，
         从 jira_issue source 中提取 issueId 作为诊断目标，不依赖用户手动告知
    found_in:
      - case: O11Y-2484314
        ws: ws-1777453881076-b4724cc4b

  - id: ISS-0066
    title: 中文输入法下 Enter 键直接发送消息（应先上屏候选词）
    type: UX
    severity: P2-medium
    status: fixed
    issue_stage: ux
    fixed_in: "PR#460"
    fix_source: autofix
    github_issue: https://github.com/tidbcloud/investibook/issues/412
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      用户使用中文输入法（IME）时，按下 Enter 键本应确认当前候选词并上屏（compositionend 事件），
      但实际触发了消息发送。正确行为：IME composition 期间的 Enter 键应仅结束输入法组合，
      不触发发送；只有在 IME 未激活时（isComposing=false）的 Enter 才发送消息。
      此外用户发现输入的英文字符会残留在 chatbot 输入框中。
    fix_plan: >
      1. 在 ChatPanel 输入框的 onKeyDown 处理器中检查 event.isComposing 或
         event.nativeEvent.isComposing，若为 true 则不发送消息
      2. 监听 compositionstart / compositionend 事件，维护 isComposing 状态标志
      3. 验证修复：在中文/日文/韩文 IME 下，候选词选择的 Enter 不触发发送，
         直接 Enter（无候选词时）正常发送
    found_in:
      - case: O11Y-2328599
        ws: ws-1776162447273-d213a514a

  - id: ISS-0067
    title: Context compaction 后诊断上下文严重丢失，导致诊断质量下降
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/416
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: investibook-core
        file: backend/investibook/core/acp.py
    description: >
      长对话诊断会话触发 context compaction 后，agent 丢失关键诊断上下文（已收集的指标、
      TopSQL 结果、SlowQuery 分析、已得出的中间结论），导致后续输出质量严重下降，甚至重复
      已做过的步骤或给出与之前矛盾的结论。用户反馈"context compaction 之后信息丢失特别严重"
      （O11Y-2530308 workspace ws-1778200904899-739292d98）。
      根本原因：agent 依赖 LLM context window 保存中间状态，compaction 截断后无法恢复，
      而 collect_evidence.py 的输出文件（evidence_summary_for_agent.txt）虽然持久化在磁盘，
      但 compaction 后 agent 不知道去重新读取这些文件。
    fix_plan: ISS-0067/plan.md
    found_in:
      - case: O11Y-2530308
        ws: ws-1778200904899-739292d98
      - case: TCID-12784
        ws: ws-1781057424629-8522f2da8

  - id: ISS-0068
    title: 基础设施瓶颈与查询问题并存时，推荐优先级排序错误
    type: REASONING
    severity: P1-high
    status: fixed
    issue_stage: recommendation
    github_issue: https://github.com/tidbcloud/investibook/issues/418
    fixed_in: >
      Verified by dev replay workspace ws-1778816672288-20374db49 on 2026-05-15:
      O11Y-2530675 now ranks TiKV infrastructure first. The diagnosis identifies EBS
      IOPS throttling and TiKV hotspot as the primary bottleneck, puts IOPS/hotspot
      remediation before SQL/statistics work, and demotes query-level work to secondary follow-up.
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      当 wait_time >> process_time（如 231s vs 10s）且存在 TiKV EBS IOPS 节流（>20%）
      或 gRPC 节点热点（>5x）时，Agent 仍将 ANALYZE TABLE（统计信息刷新）列为 P0 推荐，
      将基础设施问题（IOPS 扩容、热点排查）列为 P1。
      实际上，wait_time >> process_time 本身已说明查询在等待 IO/锁资源，
      而非执行效率低下；统计偏差是次要症状，基础设施是根因。
      O11Y-2530675 用户反馈"no need diagnose query, TiKV has problem"即因此。
    fix_plan: ISS-0068/plan.md
    found_in:
      - case: O11Y-2530675
        ws: ws-1778205637705-1d3a5a116

  - id: ISS-0069
    title: Agent 无法从 metrics 获取节点 AZ（可用区）信息
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/419
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      用户反馈"没有直接通过 metrics 查到 node 的 az 信息"（O11Y-2530308）。
      Agent 在诊断过程中无法通过现有 metrics/API 获取各节点所属的
      可用区（Availability Zone）信息，当多 AZ 部署时无法判断
      故障是否集中在特定 AZ，影响诊断质量。
      目前 collect_evidence.py 和 SKILL.md 中均无 AZ 查询路径。
    fix_plan: >
      1. 调研 Clinic API / TiDB Cloud API 中是否有节点 → AZ 的映射接口
      2. 若有：在 collect_evidence.py A0/A1 段中补充获取节点 AZ 信息，
         写入 cluster_meta 或单独的 node_topology 字段
      3. 若无直接 metrics：通过 TiDB Cloud cluster nodes API 或 cluster_meta.json
         获取节点拓扑，补充 AZ 标签
      4. 在 SKILL.md Node C 中增加：当发现单节点热点时，检查其 AZ
         并说明是否为跨 AZ 流量导致延迟升高
    found_in:
      - case: O11Y-2530308
        ws: ws-1778200904899-739292d98

  - id: ISS-0072
    title: 切换页面/导航离开后，正在运行的诊断会话被中断
    type: UX
    severity: P1-high
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/456
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/core/acp.py
    description: >
      用户在诊断会话运行过程中点击返回或切换到其他页面，之前正在进行的诊断运行被中断。
      预期行为：诊断任务应在后端持续运行，用户返回后可查看完整结果；
      或至少在离开前弹出确认提示"诊断正在进行，离开将中断会话"。
      表现：用户报告"点击返回，切出去之后，之前的运行就中断了"（ws-1778302582018-d898944fb）。
      根本原因可能是：(1) 前端 SSE 连接在 unmount 时被 AbortController 终止，
      后端 agent 进程随之停止；(2) 后端 auto-chat 未与前端生命周期解耦。
    fix_plan: >
      1. 检查前端 ChatPanel SSE cleanup 逻辑，确认 abort 时机（是否在 useEffect cleanup 时立即 abort）
      2. 后端 auto-chat 任务应作为独立的后台任务运行，不依赖 SSE 连接存活
      3. 前端：用户离开时若诊断仍在运行，弹出 beforeunload 确认提示
      4. 前端：返回已有 workspace 时，若后台诊断已完成，拉取最新消息并展示
    found_in:
      - case: GH-441
        ws: ws-1778302582018-d898944fb

  - id: ISS-0073
    title: Agent 在用户明确更正后仍坚持错误根因（Hallucinate/Wrong analysis）
    type: REASONING
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/468
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户明确告知 Agent "NLB is not the issue, please begin investigation"，
      但 Agent 仍给出错误分析（Hallucinate, wrong analysis）。
      Agent 未能正确处理用户对诊断方向的更正，可能仍依赖了被否定的线索，
      或在更正后未重新收集证据、重新推理，而是在已有错误前提上继续生成结论。
      这会严重破坏用户对诊断结果的信任。
    fix_plan: >
      1. 在 SKILL.md 中增加"用户更正处理"规则：
         若用户明确否定某数据源或结论，Agent 必须：
         (a) 确认理解用户更正；(b) 从排除后的假设空间重新查询其他证据；
         (c) 不在更正后的回复中再次提及被否定的线索作为支撑依据。
      2. 检查 ws-1778294232485-9576a4683 对话记录确认具体错误分析内容和根因。
      3. 长期：加强 Agent 的"假设-验证"循环，每个结论需有 ≥2 个独立证据，
         防止因单一假设路径导致幻觉。
    found_in:
      - case: GH-439
        ws: ws-1778294232485-9576a4683
      - case: ST-2695
        ws: ws-1778815002545-96746f0f0
      - case: GH-785
        ws: ws-1784194357449-068d68b13

  - id: ISS-0074
    title: Agent 中途停止后无法自动续跑，用户须手动 /force-continue
    type: UX
    severity: P1-high
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/490
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/core/acp.py
    description: >
      诊断会话运行过程中 agent 中途停止（未产生 complete 事件），用户发现后须手动输入
      /force-continue 才能恢复。问题在于：(1) 前端未检测 agent 停止但未完成诊断的状态；
      (2) 后端未提供自动续跑机制；(3) /force-continue 作为内部命令不应暴露给普通用户——
      应在 UI 层检测并自动重试或提供友好的"继续诊断"按钮。
      用户反馈来自 GH-489（ws-1778550532236-be61c975d，dev 环境）。
    fix_plan: >
      1. 前端：检测 agent 完成但 diagnosis complete 未出现的状态，自动弹出"是否继续诊断？"提示
      2. 后端：agent 停止时若诊断未完成，记录恢复点，支持 /force-continue 的 API 化
      3. 前端：将 /force-continue 封装为 UI 按钮（"继续诊断"），而非暴露原始命令
      4. 若 agent 异常停止超过 30s，自动发送 force-continue 续跑
    found_in:
      - case: GH-489
        ws: ws-1778550532236-be61c975d
      - case: TCOC-5266
        ws: ws-1779344143693-a9777d7df
      - case: TCID-12948
        ws: ws-1784789403368-6e7c919d8

  - id: ISS-0075
    title: 诊断结果中"没有找到根因"缺少明确失败说明和后续建议
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/491
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户反馈"没有找到根因"（GH-482，ws-1778488849796-4a58cd684，prod），
      诊断结束但未能确认根本原因时，Agent 应：(1) 明确说明"未能确认根因"及具体缺失证据；
      (2) 提供替代建议（如收集更多日志、联系专家、查看特定指标）；
      (3) 列出"已排除的假设"让用户理解分析过程。当前 Agent 在无法确认根因时
      倾向于给出模糊结论，用户无法判断是数据不足还是分析方向有误。
    fix_plan: >
      1. 在 SKILL.md Node D 增加"无法确认根因"输出模板：
         - 已收集证据摘要（哪些数据源，有无异常）
         - 已排除的假设列表及依据
         - 可能方向（需要哪些额外数据才能确认）
         - 建议动作（联系 on-call 获取更多上下文等）
      2. 禁止在证据不足时给出"根因为 X"的确定性结论，改为"初步判断为 X，置信度低，原因是..."
    found_in:
      - case: GH-482
        ws: ws-1778488849796-4a58cd684
      - case: GH-778
        ws: ws-1784093291310-12ae3247d

  - id: ISS-0076
    title: Agent 在用户声明无 SQL 执行权限时仍尝试执行 SQL 分析
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/492
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户明确告知"这是客户集群，我没有权限执行 SQL"（GH-475），但 agent 后续仍尝试
      通过 SQL 查询分析（如 SHOW PROCESSLIST、SELECT 等）。用户明确要求"请通过 log、
      top sql 等进行分析 schema、数据量和 Top SQL"。Agent 须在用户声明权限约束后
      立即切换到无 SQL 的诊断路径（仅用 metrics/TopSQL/SlowQuery/logs），而非继续
      尝试 SQL 并因拒绝失败再浪费 tool call。
      关联 GH-475/476/477（ws-1778471592021-1b62231e3，prod 环境）。
    fix_plan: >
      1. 在 SKILL.md 增加权限约束检测：若用户说"no SQL access"/"没有 SQL 权限"等，
         设置 no_sql_mode=true，后续步骤完全跳过任何 SQL 执行
      2. 在 no_sql_mode 下，A3 段（SlowQuery）和 A4 段（TopSQL）使用 Clinic API 路径，
         不使用任何需要数据库连接的工具
      3. 在诊断开头明确回复："已收到权限限制说明，将仅通过 logs/metrics/TopSQL/SlowQuery 分析"
    found_in:
      - case: GH-475
        ws: ws-1778471592021-1b62231e3

  - id: ISS-0077
    title: component_health 组件数量下降被误判为节点故障（实为监控窗口截断假象）
    type: KNOWLEDGE
    severity: P1-high
    status: open
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/508
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
    description: >
      collect_evidence.py 采集的 component_health.component_count 在查询窗口末尾接近
      当前时间或数据保留边界时，Prometheus 样本数骤减，导致 last 值远低于 first 值
      （如 tidb: 12→1，tikv: 27→11）。Agent 将此解读为真实节点下线/缩容，错误联系
      相关故障假设。GH-501 中用户明确纠正："component health 因为数据采集错误，导致的误判"。
      正确行为：窗口末尾的组件数量下降是 Prometheus 稀疏采样假象，需用 Activity Hub
      事件交叉验证后才能断定真实拓扑变化。
    fix_plan: >
      在 SKILL.md 中添加 component_health 解读规则：
      1. 若 component_count.last < component_count.first，检查查询窗口末尾是否接近
         当前时间（<30min）或数据保留边界
      2. 若是，标注为"可能是 Prometheus 采集截断，非真实节点下线"
      3. 必须用 Activity Hub 中的 ModifyClusterSize/ScaleResourcePool 事件交叉验证
         才能断定真实拓扑变化
    found_in:
      - case: GH-501
        ws: ws-1778579944582-3e343f5af

  - id: ISS-0078
    title: Agent 混淆 ModifyClusterVolume（IOPS 调整）与 ModifyClusterSize（节点数变更）
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/509
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
    description: >
      GH-501 中 Activity Hub 返回 ModifyClusterVolume 事件（调整 EBS IOPS 配置），
      Agent 在分析中将其称为 ModifyClusterSize（节点数变更），导致误以为发生了滚动重启。
      ModifyClusterVolume 仅改变卷配置，不触发节点重启；ModifyClusterSize 改变节点数，
      会触发滚动重启。两者对集群的影响完全不同，混淆会导致错误的根因联系。
    fix_plan: >
      在 SKILL.md Activity Hub 事件解读部分添加事件类型分类表：
      - ModifyClusterVolume: EBS 卷/IOPS 配置变更，无滚动重启
      - ModifyClusterSize: 节点数变更，触发滚动重启
      - ScaleResourcePool: Premium 集群扩缩容，触发滚动重启
      要求 Agent 逐字引用事件 type 字段，不允许意译/改写事件类型名称。
    found_in:
      - case: GH-501
        ws: ws-1778579944582-3e343f5af

  - id: ISS-0079
    title: Agent 在无元数据支撑时断言 EBS 卷类型（gp2/gp3）
    type: REASONING
    severity: P1-high
    status: fixed
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/510
    fixed_in: >
      Verified by dev replay workspace ws-1778818267709-298211a29 on 2026-05-15:
      the targeted TCID-12625 follow-up reads cluster metadata and reports PD volumes
      as gp3 with 3,000 IOPS / 125 MiB/s instead of guessing gp2.
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      TCID-12625 中 Agent 在诊断输出中断言 "PD instance volumes are gp2"，
      但实际 PD 卷均为 gp3（用户通过 GitHub issue #494 纠正）。Agent 未查询
      cluster_meta.json 或 TiDB Cloud 节点 API 验证卷类型，直接假设/猜测。
      gp2 是 TiDB Cloud 早期默认，近期版本已默认 gp3。错误的卷类型断言会导致
      错误的 IOPS 计算和存储性能分析结论。
    fix_plan: >
      1. 在 SKILL.md 中添加规则："EBS 卷类型（gp2/gp3）必须从 cluster_meta.json
         或 TiDB Cloud 节点 API 读取，禁止假设或推测"
      2. collect_evidence.py A0 段已采集 cluster_meta，确保 volume_type 字段被提取
         并写入 evidence_summary，供后续分析引用
      3. 当需要引用卷类型时，优先从 evidence_summary 中读取实际值
    found_in:
      - case: TCID-12625
        ws: ws-1778484823635-24419a844

  - id: ISS-0080
    title: Agent 将客户评论中的相关事件直接作为因果证据，未经指标验证
    type: REASONING
    severity: P1-high
    status: fixed
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/511
    fixed_in: >
      Verified by dev replay workspace ws-1778818267709-298211a29 on 2026-05-15:
      the targeted TCID-12625 follow-up treats dev/prod correlated delay and network
      anomaly as hypotheses, marks them unconfirmed without Clinic network metrics,
      and no longer uses customer/Jira comments as causal evidence.
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      TCID-12625 中 Agent 据客户描述"dev 和 prod 集群在同一时刻出现延迟"推断
      "共享基础设施故障"，未查询 Clinic 网络指标验证。用户通过 GitHub issue #495 纠正：
      "I cannot find any network anomalies around 21:27 JST on 4/20. Please review
      network metrics again based on the clinic data. Do not rely on the customer's comment."
      客户评论是待验证的假设，不是证据。以客户评论作为根因支撑是典型的确认偏差。
    fix_plan: >
      在 SKILL.md Node D 增加推理规则：
      1. 客户/Jira 中描述的相关事件（如"两集群同时出现问题"）是假设，须用指标验证
      2. 断言"共享基础设施原因"必须展示：两集群同时出现的网络/延迟/IOPS 指标异常
      3. 若无法从 Clinic 数据获取网络指标，应标注"无法验证共享基础设施假设"
         而非采纳客户描述作为结论
    found_in:
      - case: TCID-12625
        ws: ws-1778484823635-24419a844

  - id: ISS-0081
    title: Agent 在无日志/指标佐证时断言 etcd 磁盘 I/O 故障
    type: REASONING
    severity: P1-high
    status: fixed
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/512
    fixed_in: >
      Verified by dev replay workspace ws-1778818267709-298211a29 on 2026-05-15:
      the targeted TCID-12625 follow-up checks etcd WAL fsync/backend commit latency
      before making disk-latency claims, explicitly notes PD Loki logs are unavailable,
      and marks disk-stall log evidence as unconfirmed.
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      TCID-12625 中 Agent 得出结论 "Intermittent etcd disk I/O stalls on the PD leader
      and follower nodes caused the TSO service to slow down"，但未展示 PD 日志中的
      慢写/fsync 告警、磁盘写延迟指标或 etcd raft 日志证据。用户通过 GitHub issue #496
      要求："Please show the evidence to explain the disk stalls with application (TiDB, PD etc)
      logs or metrics." etcd/磁盘 I/O 故障是严重且复杂的基础设施结论，须有具体证据支撑。
    fix_plan: >
      在 SKILL.md 增加 etcd 磁盘 I/O 故障诊断准入条件：
      必须满足以下至少一项才能断言 etcd 磁盘 I/O 故障：
      1. PD 日志中存在包含 "slow" / "fsync" / "disk" / "etcd took too long" 的告警行
      2. 磁盘写延迟指标 P99 > 50ms（来自 Clinic 指标 API）
      3. etcd raft 日志中存在 "heartbeat timeout" 或 "leader changed" 事件
      若无上述证据，只能说"怀疑 etcd/PD 性能问题，建议进一步采集 PD 日志和磁盘指标验证"
    found_in:
      - case: TCID-12625
        ws: ws-1778484823635-24419a844

  - id: ISS-0082
    title: 诊断技能不支持 TiDB Operator（OP）客户的 Clinic 数据接入
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/522
    affects:
      - skill: clinic-cli
        file: agentkit/skills/builtin/clinic-cli/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户反馈 OP（TiDB Operator，即自建 Kubernetes 部署）客户无法通过现有诊断流程进行分析。
      当前 clinic-cli 及 tidb-clinic-diagnosis 仅对接 TiDB Cloud Clinic API（托管云），
      不支持 OP Clinic（私有化部署的 PingCAP Clinic 实例，使用独立的 endpoint 和认证）。
      Lark workspace lark-ws-c07ef671-e0c8-4f18-bc96-ae5fdb1850bd 的用户明确反映该客户为
      OP 客户，需要通过 op clinic 进行分析，但系统无法处理。
    fix_plan: ISS-0082/plan.md
    found_in:
      - case: GH-514
        ws: lark-ws-c07ef671-e0c8-4f18-bc96-ae5fdb1850bd

  - id: ISS-0083
    title: Agent 缺乏 TiDB Cloud Export/Import 操作费用估算知识
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/543
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户在 TCID-12695 workspace 中提问 TiDB Cloud Essential 集群的 Export/Import
      操作费用估算，包括：(1) ExportおよびImportにかかる金額の見積もりを追加してください
      （估算 Export/Import 的费用）；(2) Export 专用计算资源对 Essential 集群 RCU 消费
      的影响（Export 使用专用计算资源时是否占用通常工作负载的 RCU）。
      Agent 对 TiDB Cloud Serverless/Essential 集群的 Export/Import 计费模型缺乏了解，
      无法正确回答这类计费估算和资源隔离问题。
    fix_plan: >
      在 SKILL.md 中补充 TiDB Cloud Serverless/Essential 计费知识：
      1. Export 操作使用专用计算资源，读取产生的 RCU 消费独立于常规工作负载
      2. Import 操作同样使用专用资源，不占用 RCU
      3. Export/Import 费用 = 存储传输量 × 单价，参考 TiDB Cloud 定价文档
      4. 引导 Agent 在用户询问费用时参考 TiDB Cloud 官方文档给出估算，
         并说明"专用计算资源不消耗集群 RCU"的隔离特性
    found_in:
      - case: TCID-12695
        ws: ws-1778823478683-cfc756965

  - id: ISS-0084
    title: Agent 在工具返回结果中不存在的数据上产生幻觉 ID
    type: REASONING
    severity: P1-high
    status: open
    issue_stage: data_semantics
    github_issue: https://github.com/tidbcloud/investibook/issues/550
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 在 ws-1779066858883-0e03b954e 中分析 DevOps API 返回的 tenant 列表时，
      捏造了从未出现在任何工具返回结果中的 ID（`1372813089196917698` 和
      `1372813089196917633`），将其当作真实数据引用。DevOps 实际只返回了
      `1372813089209061633`、`1372813089209301464`、`1372813089209061799` 三个 ID。
      Agent 在随后的对话中承认这是"凭空捏造的幻觉错误"。
      该问题与 ISS-0073（用户更正后仍坚持错误方向）不同——本问题是 Agent 主动
      伪造了工具未返回的数据，属于更严重的幻觉类型。
    fix_plan: ISS-0084/plan.md
    found_in:
      - case: GH-547
        ws: ws-1779066858883-0e03b954e

  - id: ISS-0085
    title: Activity Hub 未被指标侧检测到的实例数量变化/重启自动引用（ISS-0039 修复范围不足）
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/559
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      ISS-0039 修复后 collect_evidence.py A5 段已采集 Activity Hub 事件，但 SKILL.md
      缺少推理规则：当诊断文本中提到实例"重启"或 component_count 下降时，必须引用
      Activity Hub 事件解释原因。TCID-12704 中 Agent 检测到 3 TiDB 实例重启，
      标注为"疑似相关"但未自动引用 Activity Hub 中的 ModifyClusterSize 34→33 事件，
      导致 scale-in → 客户连接切断 → 重试 的因果链缺失。需要用户 follow-up 才得出。
      正确行为：实例 restart_count > 0 或 component_count 下降 → 强制引用 Activity Hub
      事件 → 判断是计划内操作（scale-in）还是自发故障（OOM/crash）→ 说明对服务的影响。
    fix_plan: ISS-0085/plan.md
    found_in:
      - case: TCID-12704
        ws: ws-1779156165000-34f5ef8b3
      - case: N/A
        ws: ws-1779196521741-67b1f2f94

  - id: ISS-0086
    title: Agent 未将 PD TSO Wait Duration 纳入延迟归因分析（症状 vs 原因）
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/566
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      TCID-12704 用户反馈（GitHub issue #561）："Please consider PD client metrics too.
      I observed PD TSO Wait Duration was growing during the incident. Do you think it was
      a symptom or a cause?" Agent 诊断未查询 PD TSO Wait Duration 指标
      (pd_client_cmd_handle_cmds_duration_seconds, pd_server_tso_handle_duration)，
      无法回答 TSO 延迟是 TiDB CPU 饱和的下游症状还是独立根因。
      正确分析：TiDB CPU 高 → TSO 获取任务排队 → TSO Wait Duration 高（症状）；
      若 PD CPU/leader 正常则为症状而非根因。
    fix_plan: ISS-0086/plan.md
    found_in:
      - case: TCID-12704
        ws: ws-1779071696491-aabaf929c
      - case: O11Y-2581453
        ws: ws-1780545125287-e5d2aefe0

  - id: ISS-0087
    title: Scale-in 后负载重分配影响缺乏定量分析（+3.3% 被笼统归因为延迟原因）
    type: REASONING
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/567
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      TCID-12704 用户反馈（GitHub issue #562）："During the incident, just one TiDB node
      was down, and 33 TiDB nodes were still alive, which means that the increasing workload
      should be just +3.3%. I don't think +3.3% workload had large impacts."
      Agent 将 scale-in（34→33）的间接影响笼统表述为"剩余节点压力进一步增加"，
      未做定量分析。正确分析：CPU 75% × (34/33) ≈ 77.3%（仅 +2.3pp，直接负载影响有限）；
      延迟继续升高的主因是 TCP 连接断开引发的客户端重试风暴，而非 +3.3% 负载重分配。
      Agent 需要对 scale-in 影响做量化区分，明确区分直接负载和间接重试风暴影响。
    fix_plan: ISS-0087/plan.md
    found_in:
      - case: TCID-12704
        ws: ws-1779071696491-aabaf929c

  - id: ISS-0088
    title: clinic --env dev 参数不支持，dev 环境集群无法采集诊断数据
    type: TOOLING
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/568
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户反馈（GitHub issues #563、#564，workspace ws-1779176792765-e116e462e，
      dev.investibook.com 环境）：dev 环境集群无法诊断，clinic 命令支持 --env dev 参数
      但 collect_evidence.py 未传递该参数。collect_evidence.py 默认使用生产 Clinic 端点，
      对 dev/staging 集群的数据（存储在 dev Clinic 实例）无法访问，导致所有
      Clinic API 调用返回空结果或 404/403，诊断完全无法进行。
    fix_plan: ISS-0088/plan.md
    found_in:
      - case: N/A
        ws: ws-1779176792765-e116e462e

  - id: ISS-0089
    title: vmstorage sample limit exceeded — 大集群 P99 延迟指标查询静默失败
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/571
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      TCID-12704（cluster 10123293495242577103，GCP asia-northeast1）中，
      TiDB P99 latency 指标查询返回 "error: err: sample limit exceeded" 错误，
      来自 vmstorage 后端。collect_evidence.py 中该错误未被显式处理，
      Agent 仅在 evidence_summary errors 字段中记录了失败，诊断输出中未提示用户
      "P99 延迟数据不可用"。对大集群（TiDB 34 节点）指标查询的样本数可能超出
      vmstorage 单次查询上限（默认 30000 样本），需要通过加大 step 间隔或减小时间范围绕过。
    fix_plan: ISS-0089/plan.md
    found_in:
      - case: TCID-12704
        ws: ws-1779156165000-34f5ef8b3
      - case: TCOC-5382
        ws: ws-1781054808089-764584b34

  - id: ISS-0090
    title: Agent 使用幻觉参数 --promql 调用 clinic_cli.py metrics（正确参数为 --query）
    type: TEMPLATE
    severity: P2-medium
    status: open
    issue_stage: template
    github_issue: https://github.com/tidbcloud/investibook/issues/572
    affects:
      - skill: clinic-cli
        file: agentkit/skills/builtin/clinic-cli/SKILL.md
    description: >
      ws-1779196521741-67b1f2f94（cluster 10518506906906971664，2026-05-19）中，
      Agent 调用 clinic_cli.py metrics 时使用了 --promql 参数（该参数不存在），
      正确参数为 --query。工具报错 "error: the following arguments are required: --query"，
      Agent 在第二次重试时自行修正，但浪费了一次 tool call 并可能触发后续分析脚本的
      NoneType 格式错误（metrics.json 中对应记录为空）。
      根因是 clinic-cli SKILL.md 中未明确列出 metrics 子命令的完整参数名，
      Agent 凭记忆猜测参数名导致幻觉。
    fix_plan: ISS-0090/plan.md
    found_in:
      - case: N/A
        ws: ws-1779196521741-67b1f2f94
      - case: N/A
        ws: ws-1780543020672-995d1e0f1

  - id: ISS-0091
    title: Agent 无法批量列出或统计所有 Essential 集群数量
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/581
    affects:
      - skill: devops
        file: agentkit/skills/builtin/devops/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户提问"现在有多少 Essential 集群"，Agent 回复"cluster-metadata 只支持按单个集群查询，
      DevOps 技能也仅限租户/组织层面查询，无法直接统计集群数量"。
      Agent 缺少批量列出或跨组织统计 Essential 集群的工具支持。
      DevOps API 仅提供按 tenant_id 查询，无法跨租户聚合；
      cluster-metadata skill 仅支持单集群查询，无过滤条件（如 cluster_type=essential）。
      产品运营/支持场景下需要此类统计能力（如当前有多少 Essential 集群、按区域分布等）。
    fix_plan: >
      1. 调研 DevOps API / TiDB Cloud 管理 API 是否有按 cluster_type 过滤的列表接口
      2. 若有：在 devops skill 或新建 cluster-stats skill 中暴露该接口
      3. 若无直接接口：评估是否可通过 batch 查询（遍历所有 tenant 再聚合）实现，
         或提供预计算的 cluster 统计视图
      4. 在 SKILL.md 中补充"统计集群数量"的标准查询路径，避免 Agent 告知用户"无法实现"
    found_in:
      - case: GH-576
        ws: ws-1779350297285-c8092b16d

  - id: ISS-0092
    title: 诊断技能不支持 BYOC（Bring Your Own Cloud）集群
    type: FLOW
    severity: P2-medium
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/589
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户使用 BYOC（Bring Your Own Cloud）集群触发诊断时，系统无法处理。
      用户反馈"BYOC is not supported"（GitHub issue #588，workspace ws-1779672036445-3765fddaa，
      prod 环境，yuping@pingcap.com 创建）。BYOC 集群使用客户自有的云账户和基础设施，
      Clinic API 接入方式与托管云集群不同，当前诊断流程未针对 BYOC 场景做适配：
      (1) clinic-auth.sh 可能无法完成 BYOC 集群的认证；
      (2) collect_evidence.py 的 API 路由可能不支持 BYOC 集群 ID 格式；
      (3) 诊断开始时应检测集群类型并给出明确的"BYOC 暂不支持"提示，而非静默失败。
    fix_plan: >
      1. 确认 BYOC 集群的 Clinic 认证方式（是否有独立的 auth 端点或 token 格式）
      2. 检查 collect_evidence.py 对 BYOC 集群 ID 的兼容性（cluster_id 格式、API 路由）
      3. 短期：在诊断开始时检测 BYOC 集群类型，输出明确的"BYOC 集群暂不支持 Clinic 诊断"
         提示，并建议用户使用其他诊断方式
      4. 长期：评估 BYOC Clinic 集成可行性，制定支持路线图
    found_in:
      - case: GH-588
        ws: ws-1779672036445-3765fddaa

  - id: ISS-0093
    title: Lark bot 在同话题飞书聊天中切换到不同 Workspace（session 路由错误）
    type: UX
    severity: P2-medium
    status: in_progress
    fixed_in: "PR#763"
    fix_source: autofix
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/599
    affects:
      - skill: investibook-lark
        file: backend/investibook/core/lark_bot.py
    description: >
      用户报告 Lark bot 在同一飞书话题（topic）的聊天中，会切换到不同的 Workspace，
      触发原因未知，无法稳定复现。症状：同一个飞书话题内的连续消息被路由到不同的
      lark-ws-xxx workspace，导致 agent 上下文割裂，用户认为是同一个诊断对话，
      实际上 bot 却在不同 workspace 中响应。
      根本原因候选：(1) get_or_create_bot_session 中 thread_root_id 解析不稳定
      （Lark API 在不同消息类型下返回的 thread_id/root_id/parent_id 字段可能不一致）；
      (2) _db_get_feishu_session_by_thread_root 查找失败后创建了新 session，
      而非复用已有 session；(3) resolved_issue_id 解析差异导致 issue-first 路由走不同分支。
    fix_plan: ISS-0093/plan.md
    found_in:
      - case: GH-597
        ws: lark-ws-a55196b5-4566-4dbb-9352-4a161cfbebf7

  - id: ISS-0094
    title: IOPS 指标未加 group_right 导致聚合在 project 级别而非 cluster/instance 级别
    type: TEMPLATE
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/605
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      IOPS 相关的 PromQL 查询未使用 by (instance) 聚合，导致结果是 project 级别的
      聚合值而非 cluster/TiKV 实例级别。用户无法看到具体哪个 TiKV 节点的 IOPS 情况，
      影响热点节点识别（关联 ISS-0007）。正确做法是在所有 IOPS 查询中加入
      by (instance) 或 by (instance, cluster_id) 以保留 per-TiKV 粒度。
    fix_plan: ISS-0094/plan.md
    found_in:
      - case: N/A
        ws: ws-1779849323231-f013bf8a9

  - id: ISS-0095
    title: Evidence 面板在解析大型文件时 JSON SyntaxError 导致 UI 疯狂抖动
    type: UX
    severity: P1-high
    status: fixed
    fixed_in: "PR#612"
    fix_source: autofix
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/606
    affects:
      - skill: investibook-frontend
        file: frontend/components/StudioPanel/FileViewer.tsx
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      Evidence 面板在加载大型 evidence 文件（>43KB，line 1307）时抛出
      "SyntaxError: Unexpected non-whitespace character after JSON at position 43431"，
      导致 UI 组件陷入错误/恢复循环而疯狂抖动。根本原因候选：
      (1) collect_evidence.py 输出文件中混入了非 JSON 内容（状态行/警告），
      产生 multi-object JSON 或 JSON+extra-data（关联 ISS-0058）；
      (2) FileViewer.tsx 对所有文件无条件调用 JSON.parse()，未对 .txt 文件跳过或
      对解析失败做 fallback 降级。
    fix_plan: ISS-0095/plan.md
    found_in:
      - case: N/A
        ws: ws-1779849323231-f013bf8a9

  - id: ISS-0096
    title: kube_pod_info 指标在 Clinic data proxy 中不受支持
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/607
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户报告 kube_pod_info 指标通过 Clinic data proxy 查询时返回不支持错误。
      该指标（来自 kube-state-metrics）提供 pod→node 映射，可用于识别 TiKV 实例
      所在物理节点及可用区（关联 ISS-0069 AZ 信息获取）。data proxy 的指标白名单
      不包含 kube_* 命名空间的指标，需要通过 TiDB Cloud cluster nodes API 作为替代。
    fix_plan: ISS-0096/plan.md
    found_in:
      - case: N/A
        ws: ws-1779849323231-f013bf8a9

  - id: ISS-0097
    title: 工作区花费上限拦截诊断，用户须手动 /force-continue 才能继续
    type: UX
    severity: P2-medium
    status: fixed
    fixed_in: "PR#621"
    fix_source: autofix
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/616
    affects:
      - skill: investibook-core
        file: backend/investibook/core/session_cost.py
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
    description: >
      工作区触达 WORKSPACE_COST_LIMIT_USD 上限后，诊断流程被 cost gate 拦截中断，
      Agent 输出 "Workspace spending limit reached" 提示，要求用户手动发送 /force-continue
      才能继续。用户报告 "evidence 上限拦截"（GH-611，ws-1779849323231-f013bf8a9），
      诊断在证据采集阶段被中途打断。问题在于：(1) cost gate 触发时机不友好，
      在诊断流程中途打断，而非在 session 开始前检查；(2) /force-continue 是内部命令，
      普通用户不知道需要发送它；(3) 前端没有对 cost gate 触发做友好提示或一键续跑按钮。
    fix_plan: >
      1. 在诊断 session 开始前（而非中途）检查工作区花费上限，若即将超限则提前警告
      2. 前端：检测 "Workspace spending limit reached" 消息，自动显示"继续诊断"按钮，
         点击后发送 /force-continue
      3. 考虑对诊断会话设置更高的上限或豁免机制，避免单次诊断因花费上限被打断
      4. 与 ISS-0074（agent 中途停止）配合：统一续跑 UI，覆盖 cost gate 和 agent 停止两种场景
    found_in:
      - case: N/A
        ws: ws-1779849323231-f013bf8a9

  - id: ISS-0098
    title: 图片解析 Bedrock 模型 ID 配置与 chat 模型脱钩导致图片分析失效
    type: TOOLING
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/617
    affects:
      - skill: investibook-core
        file: backend/investibook/core/image_attachments.py
      - skill: investibook-infra
        file: deployment/kustomize/envs/
    description: >
      用户报告"分析图片失效了"（GH-610，ws-1779939725281-0e16db125，prod 环境）。
      图片解析使用独立的 INVESTIBOOK_IMAGE_PARSE_BEDROCK_MODEL_ID 配置，
      当 chat 标准模型更新（如 Claude 版本升级、inference profile 变更）后，
      image parse 配置未同步更新，导致调用废弃或不存在的 model ID，
      图片上传后分析静默失败。PR #614（f64191f）已补充回归测试验证两者对齐，
      但根本修复需要让 image parse 模型 ID 自动跟随 chat 标准模型更新，或在
      配置不一致时提供明确的错误提示而非静默失败。
    fix_plan: >
      1. 短期：通过 PR #614 的回归测试在 CI 中自动检测 image parse 与 chat 标准模型 ID 是否一致
      2. 中期：让 image parse provider 自动读取 chat 标准模型 ID（从 opencode.jsonc），
         消除双重配置；或在配置不一致时启动失败（fail-fast）
      3. 长期：图片解析失败时，前端显示明确错误（如"图片分析服务暂时不可用"）而非静默失败
      4. 验证：在 prod 环境确认 INVESTIBOOK_IMAGE_PARSE_BEDROCK_MODEL_ID 与当前 chat 模型一致
    found_in:
      - case: N/A
        ws: ws-1779939725281-0e16db125

  - id: ISS-0099
    title: Backup 任务名称超过 K8s 63 字符限制时静默 hang，缺少 UI 校验
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/619
    affects:
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
      - skill: investibook-frontend
        file: frontend/components/
    description: >
      用户创建 Backup 任务时指定了 50 字符的名称，但后端在创建 K8s Job 时自动拼上前缀 "backup-"
      和后缀 "-NNNNNNN"（共约 15 字符），最终名称超出 K8s label 的 63 字符上限。K8s 返回
      `spec.template.labels: Invalid value: must be no more than 63 characters`，Job 创建
      失败并静默 hang 住，用户无任何报错提示。案例 TCOC-5309：用户名称
      `dev-tokyo-shared-01-stg-satudora-20260526-before-2`（50字符）+ `backup-`（7字符）+
      `-2988830`（8字符）= 65字符，超限。临时解决方案：将名称限制在 ≤48 字符。
    fix_plan: >
      1. UI 输入校验：将 backup 名称的最大字符数限制为 49（64 - 15 字符前后缀）
      2. 后端错误处理：捕获 K8s Job 创建时的名称超限错误，返回结构化错误信息而非静默失败
      3. 错误提示文案：「Backup 名称过长，请使用 ≤49 个字符（当前 N 个）」
    found_in:
      - case: TCOC-5309
        ws: ws-1779938829498-cdddd9d38

  - id: ISS-0100
    title: Agent 缺乏 Changefeed 资源调度/隔离知识（多 Changefeed 资源竞争）
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      TCOC-5295（Mercari eagle-insight）：同一集群上同时运行两个 Changefeed，
      新建大规格 Changefeed（32 RCU）后，原有 Changefeed 同步速率骤降至 0。
      Agent 无法分析 Changefeed 资源竞争问题，缺少：
      (1) Changefeed 调度/资源隔离机制知识（RCU 隔离 vs 共享）；
      (2) Changefeed 饥饿的诊断路径（查看 Changefeed latency、lag、event 处理速率）；
      (3) 多 Changefeed 共存场景下的容量规划建议。
    fix_plan: >
      在 SKILL.md 中补充 Changefeed 资源竞争诊断知识：
      1. RCU 配置与实际资源调度的关系（是否真的隔离或有共享 overhead）
      2. Changefeed 饥饿的诊断指标：lag（延迟增长）、event_feed_error、resolved_ts 停止推进
      3. 多 Changefeed 场景下建议：优先排查同期创建/扩容的其他 Changefeed 是否占满资源
      4. 建议路径：查 TiKV CDC observer/capture CPU、Changefeed scheduler 日志
    found_in:
      - case: TCOC-5295
        ws: ws-1779938829498-cdddd9d38

  - id: ISS-0101
    title: 诊断缺少 TiKV Raft "peer became inactive" 等终止原因日志证据
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/626
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      节点重启/终止类告警诊断中，Agent 缺少对 TiKV Raft 层日志的专项搜索，
      无法找到终止原因的直接证据（如 "peer became inactive"、"unreachable message"、
      "failed to send heartbeat" 等网络抖动特征）。现有流程仅检查 Activity Hub（计划操作）
      和内存指标（OOM），无法区分 OOM Kill、Raft 层网络故障和其他原因。
      用户须自行猜测原因并提示 Agent 搜索特定日志 pattern。
    fix_plan: ISS-0101/plan.md
    found_in:
      - case: O11Y-2579585
        ws: ws-1780299941478-b19ee2680
      - case: O11Y-2581195
        ws: ws-1780490587198-5eba5097b

  - id: ISS-0102
    title: Agent 用 Jira ticket 的语言回答而非用户对话语言
    type: FLOW
    severity: P2-medium
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/632
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      当 Jira ticket 正文或关联信息用某种语言（如日语）书写时，Agent 用 Jira ticket
      的语言回答，而非用户在对话中使用的语言（如英语）。TCOC-5331 中用户明确反馈
      "Just because one of the tickets involved is written in Japanese does not mean
      I want the answers in Japanese"，且后续还有更严重的情况：Agent 用中文思考
      后用韩语回答（ws-1780381013195-4c467dcc2）。
      Agent 应始终用用户在对话中首先使用的语言回答，Jira ticket 语言仅作为数据源
      语言，不应影响回答语言。
    fix_plan: >
      在 SKILL.md 中增加语言选择规则：
      1. 回答语言由用户在对话中首次发送的消息语言决定（用户消息语言 > Jira ticket 语言）
      2. 若用户未发送任何消息（仅有系统触发），默认用英语回答
      3. 用户可在对话中切换语言（"please answer in English"），Agent 应立即遵守
      4. Jira ticket、日志、SQL 内容等数据源语言不影响回答语言
    found_in:
      - case: TCOC-5331
        ws: ws-1780378565019-6380ae5c7
      - case: TCOC-5331
        ws: ws-1780381013195-4c467dcc2
      - case: O11Y-2581988
        ws: ws-1780578204483-f13426462
      - case: TCOC-5382
        ws: ws-1781054808089-764584b34

  - id: ISS-0103
    title: Agent 缺乏 TiDB Cloud Serverless RCU 可用/消耗量的 Grafana 面板路径知识
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/633
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      用户询问"which grafana panel to read available vs consumed RCU?"（TCOC-5330），
      Agent 无法提供 TiDB Cloud Serverless 集群 RCU（Request Capacity Unit）
      可用量与消耗量的具体 Grafana 面板路径。Agent 缺少 TiDB Cloud Serverless
      计费/资源监控的 Grafana 看板知识，无法引导用户找到正确的监控面板。
    fix_plan: >
      在 SKILL.md 中补充 TiDB Cloud Serverless RCU 监控知识：
      1. 记录 RCU 可用量与消耗量的 Grafana 面板路径（如 TiDB Cloud Console 的
         Usage 面板路径，或 Grafana Dashboard UID/panel ID）
      2. 若 Grafana 面板路径可从官方文档获取，在 SKILL.md 中直接引用
      3. 区分 "available RCU"（计划配额）和 "consumed RCU"（已用量）的监控指标，
         并说明对应的 PromQL 查询或 Grafana 面板名称
    found_in:
      - case: TCOC-5330
        ws: ws-1780375561868-63143a2f9

  - id: ISS-0104
    title: Azure 集群的 Slow Query/TopSQL 数据代理不支持，Agent 未提前检测并告知用户
    type: TOOLING
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/640
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Clinic data proxy 明确不支持 Azure 云厂商（Azure Synapse Analytics 引擎）。
      当用户对 Azure Dedicated 集群运行诊断时，collect_evidence.py A3（slow_query）
      和 A4（topsql）段会尝试查询 data proxy，导致 schema/type handling 错误（如
      "Slow query Synapse drill-down fails on schema/type handling"）。
      Agent 未在诊断开始时检测集群云厂商并提前告知用户"Azure 集群无法获取 TopSQL/SlowQuery
      数据"，导致静默失败或令人困惑的错误信息。
    fix_plan: ISS-0104/plan.md
    found_in:
      - case: N/A
        ws: ws-1780454500112-2b3ee0a48

  - id: ISS-0105
    title: Agent 缺乏 TiDB Cloud Essential 集群控制面问题诊断知识
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/641
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      用户报告 TCID-12761 的根因"应该是 essential 控制面的问题"，但 Agent 未能诊断到
      Essential 集群控制面问题。Agent 缺少：(1) Essential 集群架构知识（共享基础设施、
      控制面生命周期管理）；(2) 控制面问题的诊断信号（PauseCluster/ResumeCluster/ScaleRCU
      Activity Hub 事件、连接数骤降、无对应 CPU/IOPS 峰值的延迟突升）；
      (3) 将不明原因的 Essential 集群异常路由到控制面排查的决策规则。
      当前 SKILL.md 聚焦 Dedicated 集群（TiKV/TiDB/PD 节点级诊断），不适用于
      Essential 的 Serverless 共享资源模型。
    fix_plan: ISS-0105/plan.md
    found_in:
      - case: TCID-12761
        ws: ws-1780481866811-7d85039da

  - id: ISS-0106
    title: Agent 缺少 TSO 服务故障的直接证据采集路径（时间戳分配失败、etcd 写入验证）
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: specialized_diagnosis
    github_issue: https://github.com/tidbcloud/investibook/issues/647
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      当诊断指向 TSO 服务异常时（如 gRPC TSO method P99 latency 飙升、PD 无法分配时间戳），
      Agent 缺少验证 TSO 故障的直接证据采集路径：
      (1) 无法回答"TSO 是否真的未能分配时间戳"（需查 PD server tso handle duration 指标
          和 pd_server_tso_handle_cmds_failed_total 计数器）；
      (2) 无法回答"etcd 写入是否成功"（需查 etcd WAL fsync latency、raftstore apply duration）；
      (3) 当用户要求查看"gRPC TSO method P99 latency"时，Agent 无法指出对应的 Grafana 面板或
          Clinic 指标查询路径，只能描述结论但无法提供可验证的证据来源。
      O11Y-2581453 用户明确要求："Show me the evidence... Which grafana panel to look at?"
      O11Y-2581988 用户明确要求："Find direct evidence. Did the TSO fail to allocate timestamps?
      Was the write to etcd successful?" — 说明 Agent 在两个独立 case 中均给出了 TSO 相关结论
      但无法支撑直接证据，用户无法自行验证。
    fix_plan: ISS-0106/plan.md
    found_in:
      - case: O11Y-2581453
        ws: ws-1780545125287-e5d2aefe0
      - case: O11Y-2581988
        ws: ws-1780578204483-f13426462

  - id: ISS-0108
    title: replay.sh --check 数据覆盖检测不支持中文诊断输出和 tidb-perf-diagnosis 多 Agent 架构
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: template
    github_issue: https://github.com/tidbcloud/investibook/issues/658
    affects:
      - skill: replayer
        file: tools/replayer/replay.sh
    description: >
      replay.sh --check 的数据覆盖检测（slowquery/logs/events）基于英文关键词匹配
      tool call title/description 和 final_text。当诊断输出为中文（如 TCOC-5382 中
      "慢查询"、"日志"、"扩容操作"）或使用 tidb-perf-diagnosis 的多 Agent 架构
      （工具调用封装为 "Evidence collection for ..."，不含 slow/loki/activity 等词）时，
      检测结果为 false，即使证据实际已采集。导致误报 gap，影响评估准确性。
    fix_plan: >
      1. 在 --check 中增加中文关键词匹配：
         slowquery += '慢查询' in all_text
         logs += '日志' in all_text or 'Loki' in all_text（大写开头）
         events += 'Activity Hub' in all_text or '活动' in all_text or '扩容' in all_text
      2. 对 tidb-perf-diagnosis 多 Agent 架构：在 --check 中检测子 agent 的
         task_result output 内容（从 tool state.output 提取文本后再做关键词匹配）
      3. 或在诊断输出中保留英文技术术语（如 "Activity Hub"、"Loki"、"SlowQuery"）
         即使主体是中文，以保证检测器可识别
    found_in:
      - case: TCOC-5382
        ws: ws-1781054808089-764584b34

  - id: ISS-0107
    title: clinic_cli.py logs 使用幻觉参数 --component/--level（正确为 --query LogQL）
    type: TEMPLATE
    severity: P2-medium
    status: open
    issue_stage: template
    github_issue: https://github.com/tidbcloud/investibook/issues/651
    affects:
      - skill: clinic-cli
        file: agentkit/skills/builtin/clinic-cli/loki/SUBSKILL.md
    description: >
      ws-1780543020672-995d1e0f1（JP0529-0604 巡检，2026-06-04）中，Agent 调用
      clinic_cli.py logs 时使用了不存在的 --component 和 --level 参数
      （正确参数为 --query，接受 LogQL 格式）。CLI 报错 "unrecognized arguments:
      --component --level"，Agent 在第二次重试时自行修正，但浪费了一次 tool call。
      与 ISS-0090（metrics 子命令 --promql 幻觉参数）是同类型问题，均因 Agent 从其他
      系统接口语义推断参数名导致幻觉。loki/SUBSKILL.md 未明确列出不存在的参数名，
      缺乏"不要使用 --component/--level" 的警示。
    fix_plan: ISS-0107/plan.md
    found_in:
      - case: N/A
        ws: ws-1780543020672-995d1e0f1

  - id: ISS-0109
    title: Lark bot 诊断完成后未将分析结果展示给用户（本地 agent 可以，Lark bot 不行）
    type: UX
    severity: P1-high
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/662
    affects:
      - skill: investibook-lark
        file: backend/investibook/api/lark.py
      - skill: investibook-core
        file: backend/investibook/core/acp.py
    description: >
      用户反馈 Investibook Lark bot 完成诊断后未将分析结果展示给用户
      （"会华丽没有展示出对应的分析结果"），但使用本地 agent 可以正常获取结果。
      这说明诊断流程本身可以成功执行（Clinic 数据可获取、agent 可完成分析），
      问题出在 Lark bot 侧：诊断完成后的结果未被正确回传到 Lark 对话中。
      可能原因：(1) Lark bot SSE 消费逻辑超时或连接中断，导致 complete 事件未触发 Lark 回复；
      (2) acp.py 中 Lark session 的消息持久化/回调路径与 web 路径不同，存在静默失败；
      (3) Lark bot 对长时间运行的诊断任务（>2 分钟）可能遭遇 webhook 超时，
      未能将最终诊断结果推送回用户。
    fix_plan: ISS-0109/plan.md
    found_in:
      - case: N/A
        ws: lark-ws-5aec03b6-1b79-4559-9c94-61ad9a2c7523

  - id: ISS-0110
    title: Studio Key Evidence 面板跨时段 Prometheus 图表 X 轴跨度过大导致无法阅读
    type: UX
    severity: P2-medium
    status: fixed
    fixed_in: "PR#699"
    fix_source: autofix
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/665
    affects:
      - skill: investibook-frontend
        file: frontend/components/StudioPanel/
    description: >
      用户请求对比两个相隔 20 天的时间段时，Studio "Key Evidence" 面板将两段数据放在
      同一张 Prometheus 图表中渲染（TIKV CPU 和 Disk IO Utilization），导致 X 轴横跨
      20 天，图表中大部分区域为空白，完全无法阅读。正确行为应为每个不连续时间窗口
      渲染独立的图表面板（并排或堆叠），或至少将 X 轴裁剪到仅包含有数据的区间。
    fix_plan: ISS-0110/plan.md
    found_in:
      - case: TCOC-5426
        ws: ws-1781673884286-667cf2c1d

  - id: ISS-0111
    title: collect_evidence.py 不采集 TiProxy 路由指标（tiproxy_session_total / tiproxy_balance_events）
    type: TEMPLATE
    severity: P3-low
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/715
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      collect_evidence.py 不采集 TiProxy 特有指标（tiproxy_session_total、
      tiproxy_balance_events），导致在 TiProxy 路由失衡场景（如 tiproxy/issues/1172
      DNS 混乱）下，Agent 无法直接确认 Zone A 零连接路由状态，只能依赖工程师 Jira
      评论作为替代证据。对于含 TiProxy 的集群，这些指标可直接量化路由分布，
      在 TiDB CPU 不均衡场景中提供一阶证据。
    fix_plan: ISS-0111/plan.md
    found_in:
      - case: TCOC-5387
        ws: ws-1782112035290-90355e8ee

  - id: ISS-0112
    title: Agent 将网络层延迟问题归因为业务/查询层（P999 突升 wait_time 维度缺失）
    type: REASONING
    severity: P1-high
    status: open
    issue_stage: classification
    github_issue: https://github.com/tidbcloud/investibook/issues/746
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      用户报告 P999 延迟突升场景中根因"彻底归因错误"——实际是网络层问题，Agent 却归结为业务/查询层。
      Agent 在延迟分析中缺少对 wait_time vs process_time 比值的优先检查；当 wait_time >> process_time
      时，应首先排查网络/IO 层（TiKV gRPC latency、Raft message duration）而非跳入 TopSQL/执行计划。
      当前 collect_evidence.py 不采集 TiKV gRPC 网络延迟指标，SKILL.md 无网络层 vs 查询层鉴别规则。
    fix_plan: ISS-0112/plan.md
    found_in:
      - case: GH-737
        ws: ws-1783480020792-e22cbc2ee

  - id: ISS-0113
    title: write_analyst_report.py 脚本在 workspace 中不存在导致 tool call 失败
    type: TOOLING
    severity: P2-medium
    status: open
    issue_stage: template
    github_issue: https://github.com/tidbcloud/investibook/issues/761
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/scripts/write_analyst_report.py
    description: >
      O11Y-2612493 诊断中，Agent 尝试调用
      /data/workspaces/ws-1783591129535-db196fe8d/.opencode/skills/builtin/tidb-clinic-diagnosis/scripts/write_analyst_report.py
      但该脚本不存在（exit 2: No such file or directory），导致 "Validate and merge
      diagnosis-analyst.json into workspace report" tool call 失败（status=failed）。
      Fallback 路径成功完成了 merge（workspace_evidence_report.json updated），
      诊断最终结果正确，但主路径的脚本缺失产生了不必要的失败 tool call。
      根因可能是脚本路径硬编码为 tidb-clinic-diagnosis，但实际 workspace 使用的是
      tidb-perf-diagnosis skill，两者路径不同。
    fix_plan: >
      1. 确认 write_analyst_report.py 是否应该存在于 tidb-perf-diagnosis skill 的 scripts 目录
      2. 若是：将脚本同步到该目录，或在 skill 安装时确保该脚本被复制
      3. 若主路径写死了 tidb-clinic-diagnosis 路径：改为动态查找当前激活 skill 目录下的脚本
      4. 验证：在 tidb-perf-diagnosis workspace 中诊断后，主路径不再失败
    found_in:
      - case: O11Y-2612493
        ws: ws-1783591129535-db196fe8d
      - case: TCID-12985
        ws: ws-1785896640589-783164024

  - id: ISS-0114
    title: AutoChat 默认超时 190s 不足以完成一轮完整诊断
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/833
    affects:
      - skill: investibook-core
        file: backend/investibook/core/acp.py
    description: >
      AutoChat 默认超时设置（190s）不足以完成一轮完整诊断（planning + evidence-agent dispatch
      + evidence collection + synthesis 合计约 300–400s），导致 agent 在思考/规划阶段消耗完预算后，
      evidence-agent 尚未执行便触发 AutoChat timeout。用户收到 "[AutoChat timeout] assistant
      response timed out." 作为最终回复，反馈为"分析が完了しませんでした"（分析未完成）。
      TCID-12948 中 AutoChat 在 190s 时触发，此时 agent 仅读取了工作区上下文文件并完成规划，
      尚未发起任何数据采集工具调用。
    fix_plan: >
      1. 将 AutoChat 超时从 190s 延长至 600s（与 replay.sh --max-time 600 一致）
      2. 或：在 agent 规划完成后立即 checkpoint，超时时重启 agent 并跳过规划阶段直接执行
      3. 或：将超时设计为"无 tool call 进展后 N 秒"而非绝对时长，避免因规划耗时过长而误触发
      4. 参考 ISS-0074（agent 中途停止后续跑），统一前端 UX：超时后自动触发续跑而非显示错误
    found_in:
      - case: TCID-12948
        ws: ws-1784858628538-fa0f798a0

  - id: ISS-0116
    title: 慢查询 time 字段 epoch 换算错误导致多次无效查询
    type: TEMPLATE
    severity: P2-medium
    status: open
    issue_stage: template
    github_issue: https://github.com/tidbcloud/investibook/issues/841
    affects:
      - skill: clinic-cli
        file: agentkit/skills/builtin/clinic-cli/data-proxy/SUBSKILL.md
    description: >
      Agent 对 clinic_data_proxy.slow_query_logs 的 `time` 字段进行 epoch 过滤时，
      手动换算告警时间的 epoch 值出错（O11Y-2622673 中差了约 364 天：1753341151 vs 正确值 1784877751），
      导致 3+ 次查询返回空结果，浪费约 8 次工具调用后才通过 time-conversion skill 纠正。
      根因是 SKILL/SUBSKILL.md 未提示：使用 time 过滤前应先执行 `SELECT MIN(time), MAX(time)`
      确认字段的实际 epoch 范围，避免基于错误 epoch 的无效窗口查询。
    fix_plan: >
      在 clinic-cli data-proxy/SUBSKILL.md 中增加"慢查询时间过滤最佳实践"：
      1. 使用 time 字段过滤前，先执行 SELECT MIN(time), MAX(time) 确认实际 epoch 范围
      2. 使用 time-conversion skill 换算告警 ISO 时间为 epoch（不手动计算）
      3. 样例：告警时间 2026-07-24T07:22:31Z → python3 time_convert.py dt-to-ts → 1784877751
    found_in:
      - case: O11Y-2622673
        ws: ws-1784878020053-9144f262a

  - id: ISS-0117
    title: clinic_data_proxy SQL 聚合字段需 CAST(x AS UNSIGNED)，不支持 CAST(x AS INT64)
    type: TEMPLATE
    severity: P2-medium
    status: open
    issue_stage: template
    github_issue: https://github.com/tidbcloud/investibook/issues/842
    affects:
      - skill: clinic-cli
        file: agentkit/skills/builtin/clinic-cli/data-proxy/SUBSKILL.md
    description: >
      Agent 在 clinic_data_proxy.slow_query_logs 中对字符串型数值字段（process_keys、total_keys）
      执行聚合时，使用了 BigQuery/SparkSQL 风格的 `CAST(x AS INT64)` 语法，导致 3 次工具调用
      失败（"SQL rewrite error"/"syntax error"）。clinic data proxy 使用 MySQL 方言，
      正确语法为 `CAST(x AS UNSIGNED)` 或 `CAST(x AS DECIMAL)`。SUBSKILL.md 未说明字段类型
      和正确的 CAST 语法，Agent 凭其他系统经验猜测导致反复失败。
      与 ISS-0090（--promql 幻觉参数）和 ISS-0107（--component/--level 幻觉参数）属同类模式：
      缺少明确的参数/语法约束导致 Agent 猜测失败。
    fix_plan: >
      在 clinic-cli data-proxy/SUBSKILL.md 中增加"字段类型和聚合语法说明"：
      1. 明确 slow_query_logs 中 process_keys/total_keys/query_time 字段为 STRING 类型
      2. 正确聚合语法：SUM(CAST(process_keys AS UNSIGNED))，不要用 INT64/BIGINT
      3. 添加反例警示："不支持 CAST(x AS INT64)，这是 BigQuery 语法，data proxy 是 MySQL 方言"
      4. 提供一个完整的聚合查询模板供 Agent 直接参考
    found_in:
      - case: O11Y-2622673
        ws: ws-1784878020053-9144f262a

  - id: ISS-0118
    title: Expensive query 类告警诊断仅限于 slow_query_logs，缺少 metrics/TopSQL 佐证
    type: FLOW
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/876
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
    description: >
      O11Y-2622673（expensive query 类告警）诊断中，Agent 整个过程仅使用 clinic-cli
      查询 slow_query_logs，未查 metrics（CPU、QPS、P99 延迟趋势）、TopSQL（CPU 归因）、
      Activity Hub 事件。仅凭 slow_query 数据无法量化告警触发时系统整体压力，也无法
      形成完整的"负载 → 系统影响 → 告警"因果链。ISS-0043（已修复）解决了 tidb-clinic-diagnosis
      skill 的同类问题，但 tidb-perf-diagnosis skill 的 expensive query 诊断路径
      未受益于该修复——Agent 仍只调用 clinic_cli.py sql 而不采集 metrics 和 TopSQL。
    fix_plan: >
      在 tidb-perf-diagnosis SKILL.md 的 expensive query 诊断路径中，要求同时采集：
      1. 告警时间窗口的关键 metrics（QPS、TiDB CPU、P99 延迟）以量化系统整体压力
      2. TopSQL（如可用）以归因 CPU 消耗来源
      3. 已有 slow_query_logs 分析作为主要证据，metrics 和 TopSQL 作为佐证
      参考 ISS-0043 fix 在 tidb-clinic-diagnosis 中的实现方式。
    found_in:
      - case: O11Y-2622673
        ws: ws-1784878020053-9144f262a

  - id: ISS-0119
    title: collect_evidence.py 在 GCP 集群上将 EBS IOPS 误报为 0（GCP 无 EBS，应使用 GCP PD 指标）
    type: TEMPLATE
    severity: P2-medium
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/908
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      collect_evidence.py 的磁盘指标采集段（A1）使用 EBS IOPS 相关的 PromQL 查询，
      但 GCP 集群无 EBS（使用 GCP Persistent Disk），导致所有 EBS 指标均返回 0.00
      或空值，给 Agent 造成"磁盘 IOPS 正常"的错误印象。在 TCID-12948 中，
      Agent 正确识别了"EBS IO Utilization = 0.00 是因为 GCP 无 EBS"并转而分析
      GCP PD write throughput，但这依赖 Agent 的先验知识，而非 collect_evidence 的正确引导。
      对于 GCP 集群，应改用 GCP Persistent Disk 对应的指标（如 node_exporter 的
      node_disk_written_bytes_total、node_disk_io_time_seconds_total 等）。
    fix_plan: >
      1. 在 collect_evidence.py A1 段检测集群云厂商（从 cluster_meta.json 读取 cloud_provider）
      2. 若 cloud_provider = "GCP"：使用 GCP PD 对应的 node_exporter 磁盘指标：
         - 写入吞吐：rate(node_disk_written_bytes_total[5m])
         - 读取吞吐：rate(node_disk_read_bytes_total[5m])
         - 磁盘使用率：rate(node_disk_io_time_seconds_total[5m])
      3. 若 cloud_provider = "AWS"：保持现有 EBS IOPS 查询不变
      4. 在 evidence_summary 的 disk 字段中标注云厂商及实际使用的指标类型
    found_in:
      - case: TCID-12948
        ws: ws-1784858772091-b5f9b6847

  - id: ISS-0120
    title: Agent 未识别 O11Y 告警的 cluster ID 指向 k8s infra 集群而非用户 TiDB 集群
    type: KNOWLEDGE
    severity: P1-high
    status: open
    issue_stage: intake_context
    github_issue: https://github.com/tidbcloud/investibook/issues/995
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      O11Y 告警中携带的 cluster ID 有时指向运行监控系统的 k8s 基础设施集群
      （infra/ops 集群），而非实际出现性能问题的用户 TiDB 集群。
      Agent 未在诊断开始前验证 cluster ID 的业务属性，直接对 k8s infra 集群
      进行 Clinic 数据采集和诊断，导致分析方向完全偏离实际问题集群。
      用户反馈："被 o11y cluster id = k8s infra 带偏了"。
    fix_plan: >
      1. 在 collect_evidence.py A0 段（cluster 元数据采集后）增加 cluster 类型验证：
         从 cluster_meta.json 读取 cluster 名称/标签，若包含 "infra"/"k8s"/"ops"/
         "monitoring"/"observability" 等特征，输出警告并停止采集
      2. 在 SKILL.md intake 阶段增加规则：若 cluster_meta 显示非用户 TiDB 集群特征，
         向用户明确说明"当前 cluster ID 疑似为 k8s 基础设施集群，请确认或提供正确的集群 ID"
      3. 文档化已知的 infra cluster ID 特征（如命名规则、project/org 标记）以辅助识别
    found_in:
      - case: O11Y-2634149
        ws: lark-ws-1d2debe1-f617-44f2-856e-f030abf122ee

  - id: ISS-0121
    title: RCU available_ru=0 被归因为延迟叠加因素，但未用 request_p90 量化 RCU 限流 overhead
    type: REASONING
    severity: P2-medium
    status: open
    issue_stage: classification
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
    description: >
      当 resource_control available_ru=0 时，Agent 将 RCU 耗尽归为延迟"叠加机制"，
      但未读取 request_p90 指标来量化 RCU 限流对每个请求的实际 overhead。
      在 TCID-12985 中，request_p90=0.5ms（0.0005s），RCU 限流开销极小；
      用户提高 RCU 后延迟无改善，说明 RCU 并非主因。
      available_ru=0 + 高 RCU 消耗是 CPU 饱和的结果（CPU 慢 → SQL 慢 → 消耗更多 RU），
      而非延迟原因。Agent 需要用 request_p90 来量化，才能正确区分"RCU 耗尽是因还是果"。
    fix_plan: >
      在 SKILL.md / collect_evidence Resource Control 分析规则中增加：
      1. 当 available_ru=0 时，必须读取并报告 request_p90（resource_control_request_p90 指标）
      2. 若 request_p90 < 5ms：RCU 限流开销极小，不是延迟主因；available_ru=0 是 CPU/工作负载的结果
      3. 若 request_p90 > 50ms：RCU 限流显著影响延迟，是叠加或主因
      4. 在 evidence_summary 的 resource_control 段已包含 request_p90，Agent 应主动读取并对比
    found_in:
      - case: TCID-12985
        ws: ws-1785896640589-783164024

  - id: ISS-0122
    title: 慢查询 wait_time >> process_time 时缺少 wait_time 子项分解分析
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      当慢查询 wait_time >> process_time 时，Agent 认定为"TiDB goroutine 排队"即停止，
      未进一步分解 wait_time 来源。TiDB slow log 包含 Connection_wait_time、lock_time、
      Plan_wait_time、Preproc_time 等子项，可以精确定位 wait 中各组件的占比。
      在 TCID-12985 中，用户明确要求"从 slow query 中看 latency 最长的部分来自哪里"，
      Agent 展示了 wait_time=1.81s vs process_time=0.03s 后即得出结论，
      未回答"这 1.81s 的 wait 具体来自哪里"。
    fix_plan: >
      1. 在 collect_evidence A3b 段（slow query detail fetch）增加对 wait_time 子项字段的提取：
         Connection_wait_time, lock_time, Plan_wait_time, Preproc_time
      2. 在 SKILL.md 增加 wait_time 分解分析规则：
         当 wait_time > process_time * 3 时，提取上述子项并报告最大占比项
      3. 若子项中 Connection_wait_time 最大 → TiDB goroutine pool 排队（确认 CPU 饱和）
         若 lock_time 最大 → 锁竞争
         若 Plan_wait_time 最大 → 执行计划缓存问题
    found_in:
      - case: TCID-12985
        ws: ws-1785896640589-783164024

  - id: ISS-0123
    title: Essential 集群 CDC 诊断缺少 TiCDC 专有指标采集（resolveTs lag、replication worker 占用）
    type: TEMPLATE
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    github_issue: https://github.com/tidbcloud/investibook/issues/1073
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py
    description: >
      在 CDC resolveTs lag 类告警诊断中，collect_evidence.py 未采集 TiCDC 专有指标
      （ticdc_processor_resolved_ts_lag、ticdc_replication_task_status、replication worker
      占用率等）。Agent 只能从 TiKV/TiDB 侧指标分析，无法直接观测 TiCDC 层瓶颈，
      导致 TCOC-5841 中错误地将 TiKV resolve_lock 高延迟归因为 resolveTs 停滞的根因，
      实际根因是邻居集群 changefeed 占用了共享 replication worker（noisy-neighbor）。
    fix_plan: >
      1. 在 tidb-perf-diagnosis/tidb-clinic-diagnosis 的 collect_evidence.py 中增加
         CDC 证据采集段：对 CDC 类告警（resolveTs lag、changefeed error、cdc 关键词）激活
      2. 采集指标：ticdc_processor_resolved_ts_lag、ticdc_replication_task_status、
         ticdc_sink_write_rows_rate（下游写入速率）、worker 槽位占用率
      3. 对 Essential shared 集群：额外说明 replication worker 为 shared pool 内共享资源，
         noisy-neighbor 是合法的瓶颈假设
      4. 将 TiCDC 专有指标写入 evidence_summary_for_agent.txt 供后续分析引用
    found_in:
      - case: TCOC-5841
        ws: ws-1787286760265-167b90c0a

  - id: ISS-0124
    title: Essential 共享集群 TiCDC noisy-neighbor 场景缺少诊断路径（replication worker 无租户隔离）
    type: KNOWLEDGE
    severity: P1-high
    status: open
    issue_stage: specialized_diagnosis
    affects:
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
    description: >
      Agent 未将 Essential 集群 TiCDC 层视为多租户共享资源。Essential（shared v2）集群
      的 TiCDC replication worker 在同一 shared pool 内无租户级硬隔离，单个邻居集群的
      changefeed 可以耗尽 worker 资源，导致其他集群的 changefeed 无法推进 resolveTs。
      TCOC-5841 中 Agent 未将 noisy-neighbor 列入假设，直接从 TiKV 侧指标分析，
      需要用户明确更正后才得出正确根因。
    fix_plan: >
      1. 在 tidb-perf-diagnosis SKILL.md 的 Essential 集群特殊场景知识库中补充：
         TiCDC replication worker 为 shared pool 内多集群共享，无租户级配额隔离
      2. 当 Essential 集群出现 CDC resolveTs lag 且本集群 TiCDC sink/metrics 无明显异常时，
         应提示"noisy-neighbor 假设：检查同一 shared pool 内是否有邻居集群 changefeed 占用大量 worker"
      3. 建议缓解方案：对邻居 changefeed 设置 throughput-limit 或临时暂停；
         长期建议平台侧实施 replication worker 的租户级配额管控
    found_in:
      - case: TCOC-5841
        ws: ws-1787286760265-167b90c0a

  - id: ISS-0125
    title: Feedback 按钮短时间内可多次提交导致创建重复 GitHub issue
    type: UX
    severity: P2-medium
    status: open
    issue_stage: ux
    github_issue: https://github.com/tidbcloud/investibook/issues/1074
    affects:
      - skill: investibook-frontend
        file: frontend/components/ChatPanel/index.tsx
      - skill: investibook-core
        file: backend/investibook/api/workspaces.py
    description: >
      用户在 TCOC-5841 workspace 中连续 3 次点击 feedback 按钮（04:47:23/04:47:36/04:47:56，
      33 秒内），每次均成功创建 GitHub issue（#1064/#1065/#1066），三条内容完全相同。
      feedback 提交后按钮未进入禁用/loading 状态，后端无幂等去重，导致重复 issue。
      这给 replayer postmortem 流程造成干扰（同一 workspace 被发现 3 次）。
    fix_plan: >
      1. 前端：feedback 提交成功后立即禁用按钮并显示 loading/success 状态，防止重复点击
      2. 后端：/issue 接口增加幂等检查：相同 workspace_id + 相同 feedback 内容在 60s 内
         只允许创建一条 GitHub issue（通过 workspace+content hash 去重）
      3. 可选：Phase 8 replayer 在处理 auto-created issues 时，对同一 workspace 的重复 issue
         自动去重，只处理最新一条
    found_in:
      - case: TCOC-5841
        ws: ws-1787286760265-167b90c0a

  - id: ISS-0126
    title: Essential 集群 changefeed stuck-creating 应优先查 Activity Hub 和 operation logs，而非 TiCDC 容器日志
    type: FLOW
    severity: P1-high
    status: open
    issue_stage: data_retrieval
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
      - skill: tidb-perf-diagnosis
        file: agentkit/skills/builtin/tidb-perf-diagnosis/SKILL.md
    description: >
      Agent 对 changefeed stuck-creating 场景，默认进入 TiCDC 容器日志 + 指标查询路径。
      对 Essential 共享集群，TiCDC pod 未建立时此路径天然返回空（stream_count=0），
      Agent 花费大量 tool call 反复尝试不同的 label 组合，最终以"低信心"输出。
      正确路径：先查 Activity Hub 确认 ResourceLimitation 事件，再查 manager operation logs
      验证 TiCDC pod 是否曾被调度——若两者均确认则直接判定为 provisioning gate 阻断，
      无需查 TiCDC 容器日志。TCOC-5870 中 Agent 需要用户明确指出方向才转向正确路径。
    fix_plan: >
      在 SKILL.md CDC 诊断路由规则中增加：
      1. changefeed stuck-creating（非 stuck-running）→ 优先查 Activity Hub ResourceLimitation 事件
      2. 若有 ResourceLimitation 事件 → 查 manager/operator operation logs 确认 ticdc pod 是否被调度
      3. manager logs 中 0 次 "ticdc" + ResourceLimitation 存在 → 直接判定 provisioning gate 阻断
      4. 不在 TiCDC 容器日志/指标上投入 tool call（pod 未建立时无意义）
    found_in:
      - case: TCOC-5870
        ws: ws-1787726443146-f759396bc

  - id: ISS-0127
    title: Essential 集群 ResourceLimitation 阻断 TiCDC 时建议 RCU headroom 应基于 provisioning gate 逻辑
    type: KNOWLEDGE
    severity: P2-medium
    status: open
    issue_stage: recommendation
    affects:
      - skill: tidb-clinic-diagnosis
        file: agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md
    description: >
      Agent 建议"提高 maxRCU 至 ≥70000-100000"基于"2x headroom"保守估算，
      与 Essential tier TiCDC provisioning gate 的实际判断逻辑无关。
      用户追问时 Agent 坦承是"拍脑袋的"，并向用户询问 provisioning gate 条件。
      正确行为：对 Essential 集群，provisioning gate 只需 provisionedRCU < maxRCU（任何余量即可）；
      若 cdc-RCU=1，则提高 maxRCU 超过当前 workload peak 仅需极小余量，不需要 2x。
      Agent 不应在 recommendation 阶段向用户询问平台内部逻辑，应从 changefeed 配置或
      知识库获取 cdc-RCU 消耗，或明确说明"不确定，建议联系平台团队"。
    fix_plan: >
      在 SKILL.md ResourceLimitation 处理规则中补充：
      1. 建议 maxRCU 调整量时，先读取 changefeed 的 cdc-RCU 配置（API 或 cluster_meta）
      2. provisioning gate 条件：provisionedRCU + cdc-RCU-cost < maxRCU 即可解除阻断
      3. 若 cdc-RCU=1，只需 maxRCU > 当前 provisionedRCU peak + 1，不需要 2x headroom
      4. 若 cdc-RCU 无法获取，明确输出"无法精确估算，建议联系平台团队确认 TiCDC provisioning 对 RCU 余量的最低要求"
    found_in:
      - case: TCOC-5870
        ws: ws-1787726443146-f759396bc