Skip to content

pillumina/ascend-sleuth / skills/resume-diagnosis

resume-diagnosis

Verified

续接一个被打断的昇腾诊断 session;也用于接手另一台机器打包过来的诊断(交接包)。 读活跃的 traces/*.yaml(每个并发诊断一个文件,含 trace),复述上次停在哪一步、排除了哪些 case、当前 active case,等人贴回命令输出后继续。 也可只查一条已收尾案例的上游状态:跑 verify_upstream_outcomes 并按四种结局各说一句 (不续接、不写 trace)。 诊断被会议/上下文 compact 打断、或跨机(前一台机器上定位到一半、日志在另一台机器上)继续定位时用。

FileKindSize
SKILL.mdskill md16.9 KB
---
name: resume-diagnosis
description: >
  续接一个被打断的昇腾诊断 session;也用于接手另一台机器打包过来的诊断(交接包)。
  读活跃的 traces/*.yaml(每个并发诊断一个文件,含 trace),复述上次停在哪一步、排除了哪些
  case、当前 active case,等人贴回命令输出后继续。
  也可只查一条已收尾案例的上游状态:跑 verify_upstream_outcomes 并按四种结局各说一句
  (不续接、不写 trace)。
  诊断被会议/上下文 compact 打断、或跨机(前一台机器上定位到一半、日志在另一台机器上)继续定位时用。
---

# Resume Diagnosis

诊断不是连续时段——你正跑 check 命令,被拉去开会,回来 agent 上下文已被 compact,诊断链路丢失。

## 接手外来交接包(跨机那一半)

上家把一单打包带过来时(典型:路由与验证在前一台机器上做到一半,真正的大日志在另一台机器上),**不要用 `/diagnose` 重开一单**——那会把它当新问题重新收集、重新路由,得到的是一份与上家不同的现场,而真实状态本来就在包里。

1. **落位(机械动作归脚本)**:`python3 scripts/import_trace.py <包.zip | 包.md | 包目录>`——它校验包、落到 `traces/`、比对知识库版本、点出缺件,并打印一屏交接简报。同名冲突时它落成 `<sid>-imported-<n>` 而**不自动合并**(两台机器为同一个问题各开一单是常态,要不要合并是判断,交人);同一份包重复接手它不重复落位。
2. **读那句简报 + `traces/handoff/<sid>.yaml`**(外来单才有这个文件,是交接单的机器可读那一份):来源主机与知识库版本、交接意图(继续定位 / 复核结论 / 转上游)、上家留下的待补材料(`needs`)、未纳入与未内联的清单。
3. **版本不一致照实说**:本机知识库与上家不同时简报会点出来——`excluded_cases` 里的 id 可能不存在、候选排序可能不同。以本机库为准执行,发现候选集与 trace 记的对不上就如实说明,别把差异当成上家写错。
4. **缺件不等于"证据已齐"**:简报点名的 `missing`(单文件 md 通道未内联的大文件、传输丢件)要在第一屏就讲清,并按 `needs` 索取;缺着它们把上家的结论当已验证继续往下推,是把"上家没验完的部分"冒充成已验证。
5. **然后照下面的主流程续接**——外来包接手只负责把现场放到本地,恢复现场与继续定位的规则一条不变。

## 只查上游(不续接)

已收尾的单不在可续接之列(`status: resolved` 不续接),但它可能带着上游锚点。这时要知道的是
"上游动了没有",不是"上次查到哪一步":这条路径**不续接、不写 trace、不改状态**,只做一次查证,
外加一句判断。

1. 跑 `python3 scripts/verify_upstream_outcomes.py --case <case-id>`。默认就是 dry-run,不写任何文件;
   `--case` 可重复,按名单一次查几条。案例没有上游锚点时它不发查询,只在汇总里报一行「不可对照」。
2. 按结局说一句话,四种结局分开讲:
   - `上游确认`(issue 关闭为 completed / PR 已合入 / 旧 issue 由提交关闭):内容被上游证实了。
     **这不等于你的部署已有这个修复**——要升级建议就先做落地实证(`skills/diagnose` 步骤 5 与
     `skills/diagnose/references/diagnosis-procedure.md` 的「上游修复的落地实证」)。写回 `validation_record` 再加
     `--apply`;写回是知识库改动,走 PR。
   - `上游否定`且案例声明修复已合入(脚本把这条印成 `[矛盾]`,退出码 1):停,交人判——是改锚点
     (指向修复 PR)还是改案例结论。dry-run 下脚本只把它列进「本次将写回」的计划,`--apply`
     并走 PR 之后才真的记 `inconsistent`——别说成「已经记了」。
   - `未验证`(issue 仍 open / 没有 PR 合入):上游还没有结论。**不写任何字段**——「没证据」不是
     负结论。
   - `不可查证`(无 gh、未登录、网络失败、限流):报查不到,不猜结局。
3. 结果只进对话,不进 trace:`resume` 事件只属于续接,这条路径一行 trace 都不写。

## 流程

**先清反馈债——按 `feedback.case` 的取值分三种,别混**:扫到的 state 文件里若有 `feedback.outcome: pending`,先看 `feedback.case` 是**真实 case id**、占位串 `pending-investigation`,还是**空值/缺失**(三种都出现过,定义见 `diagnosis_state.yaml.example`)。

- **真实 case id**(上次命中 case 并给了可应用 fix):追问“上次 <case-id> 的 fix 应用后解决了吗?(解决 / 没解决 / 部分解决)”——trace 记 `{action: feedback, case, outcome}`、把 `feedback.outcome` 从 `pending` 改成实际结果,再进入续接——**计数不在这里写**,由知识整理收尾的结算步骤落进条目使用记录。
- **占位串 `pending-investigation`**(没命中 case,只给了建议):**不念这个占位串**(它不是 case id),也**不要求记 feedback 结算**(没有 case 可结算,结算脚本只会跳过它)。这类单等的是**现场材料**:按顶层 `last_action` 追问上次要求的那几项材料拿到了吗(没有它才退到最近一条 `evidence.missing`),把新证据接回诊断主循环。它**不是终态**——`status` 仍是 `in_progress`;结论出来时结果记在 `status` 与 `summary`,并把遗留的 `feedback.outcome: pending` 清掉(无命中单不用反馈轴承载结果,否则会出现“状态已结、反馈轴仍挂着”的两轴打架)。
- **空值/缺失**(写了 `outcome: pending` 却没填 `case`):**一个字都别念**——照字面追问会问出“上次 的 fix 应用后解决了吗”,读者无从判断你在指哪一单。按占位串那一路处理(问现场材料、不记结算),并**顺手把这笔写清**:该单没命中就清掉 pending,确实在等材料就补成 `pending-investigation`。空值悬在那里,下次续接还得再猜一遍。

状态与结局词表见仓库根的 `trace-status.yaml`(**不是** `feedback_pending` 那个旧说法)。两条轴各管一件事:`status: resolved` 表示**诊断已收尾**(根因定位明确),不表示 fix 生效;fix 行不行只由 `feedback.outcome` 记。命中单在给 fix 时挂 `pending`,这里追问后追加 `feedback` 事件改值——**改的是 outcome,不是给 status 补一句"修好了"**(status 早在收尾时就该落)。

**这份债为什么由续接来清、而不是由新诊断开屏来问**:续接续的正是那一单,问得其所;新问题的第一屏只服务新问题——`/diagnose` 若在开屏逐单追问历史 pending(积压时可能十几单),那是审讯,不是诊断。其他 pending 挂面板待办面(谁欠、哪一单、欠多久),人到那儿清。

**续接只清被续那一单,不顺手清算全库**:工程师开局说"继续上次那个"、或面板把某一单推过来时,只处理那一单的 pending。扫到**别的** session 还挂着 pending 时,**一句话带过**(几笔、最早那笔挂了多少天、"面板待办面有『补反馈』入口"),**不在新诊断的开屏逐单念**、也不要求他当场逐笔回报——积压时那是审讯,不是诊断。想看全量债账的人去面板;续接的职责是把手上这一单推完。

0. **先解析 trace 目录**:`python3 scripts/shared_dir.py traces` 打印的绝对路径就是本会话要读写的 `traces/`(锚在**主检出**、跨 worktree 共读)——下面所有 `traces/…` 读写都以它为准,别写相对 `traces/`。
   解析后**先同步再比漂移**:`kb_drift.py` 会先调 `kb_sync.py` 做一次 fetch(只拉不合——诊断正在进行,不改工作区),再比 `kb_rev..远端分支` 与 `git status -- knowledge/`。

   输出分两种说清:
   - 「远端已合入这单用过的 case」;
   - 「本机未同步(落后未合并,旧内容下的结论仍成立,同步后要重验)」。

   后者给显式命令 `python3 scripts/kb_sync.py --merge --force`(跳过失败缓存直接试 ff-only,失败即报)。有漂移就先点出「这条 case 变了、按新内容重验」,再继续;没有 `kb_rev` 的旧单报「不可比」,不阻塞。
1. 读活跃的 `traces/*.yaml`(每个并发诊断一个文件;模板见 `diagnosis_state.yaml.example`,含 `trace` 数组)。**多个时列出让工程师选续接哪个**
   - **先看有没有配套的人读报告** `traces/<session_id>.report.md`(diagnose 步骤 6 产出):它把结论、证据链、源码分析、机制图、修复方案、**当前状态与下一步**、**沉淀候选**集中在一处。先读报告能最快恢复"这单在查什么、停在哪、待回报什么",也直接告诉你**这次能沉淀什么知识**(顶层 `sediment_candidates` 是同一份内容的结构化版本)。读报告**不替代**读 trace:报告的结论要用 trace 的 `reason`/证据核对,两者冲突时以 trace 的现场记录为准并记下冲突。
   - **报告是活件——续接中要顺手修订它**(不是只读):把新证据并入第 3 节对应强度段、更新第 7 节"当前状态与下一步"、必要时补第 4/5 节、元信息"最后更新"与第 10 节追加一行修订记录;**同一份文件改到底,不另起一份**。规则见 `skills/diagnose/references/report-template.md` 第 2 节。
   - 报告不存在(老 session 或未走完步骤 6)→ 照下面第 2、3 步从 trace 恢复,不视为异常。
2. **恢复完整现场(读 trace 全轨迹,不只元信息)**:
   - 复述:session_id、status、current_step、已排除的 case(`excluded_cases`)、当前 active_case、`last_action`(上次等你做什么)
   - `last_action` 是**当前**提问:按它追问上次要的材料或决定拿到了吗;历史 `evidence.missing` 只作背景,不逐条重问。拿到回答后改写或清空 `last_action`,再继续。
   - **读 trace 数组恢复对话上下文**:上次问了用户什么、用户已回答了什么、已排除哪些候选及原因(`reason`)——续接是**接着上次的对话继续**,不是从头开始(用户已提供的信息不重复要)
3. **证据确认(跨 agent/session 的关键——agent 无法自证摘要够,必须用户裁决)**:
   - **复述证据清单**:每个 user 事件的 `content`(摘要)+ `evidence`(内联了什么 / 引用了哪些文件 `files` / 来源 `sources` / 已知缺口 `missing`)
   - **问用户:"证据齐全吗?有遗漏吗?"**——跨 agent 时新 agent 只见过摘要,无法判断摘要是否等于原文;`missing` 字段自动列出已知缺口。用户确认齐全 → 继续;用户补充 → 更新该 user 事件的 `evidence` 后再继续
   - **文件证据可读**:`evidence.files` 是相对仓库路径(`traces/evidence/<session_id>/`),同工作区可直接读;读不到 → 问用户要
4. **续接必写 trace(与 diagnose 同要求,闭环关键)**:确认续接开始后,往 `traces/<session_id>.yaml` 追加一条 `{role: agent, action: resume, harness_session: "$DSH_SESSION_ID", step: <current_step+1>, output: "续接 <session_id>,恢复到 step <N>"}`,**并刷新顶层 `updated_at: <ISO 时间>`**——这是诊断面板"最新活动置顶"的依据(续接 = 该 session 又活跃了);后续续接中的关键决策同样带 `reason`(与 diagnose 的 trace 要求一致)。`harness_session` 写当前会话号,**顶层 `harness_session` 保持原始值不覆盖**:前者让状态条与跳转知道这一单在哪个会话被接手,后者继续用于成本 / 工具调用归因。续接中更正旧结论或来了新证据时,按三步走:
   - **先追加一条 user 事件**:`content` 写摘要,`evidence` 把新证据落进 `traces/evidence/<session_id>/`(铁律与 diagnose 相同,不写指纹)。
   - **再走 content 写入口**改 `summary` 与现场侧 / 日志过程 / 上游查证三段(`incident_timeline` / `failure_process` / `upstream_timeline`):`python3 scripts/trace_transition.py <session_id> --field content --content-file <json> --by agent --json`。`kind` 取 `fact_corrected` / `conclusion_overturned` / `scope_changed` 等,`reason` 写触发来源;写入口按 id 比对自动生成一条 `revisions`。
   - **最后修订报告**:对应小节、元信息「最后更新」、第 10 节修订记录各改一处;旧结论降级标注,不删。

   **不要手改 YAML**:手改没有修订记录,`hashes` 对不上,`verify_trace_status.py --all` 会报出来。改当前值只走 content 写入口这一条路。

5. 等人执行上次要求的命令并贴回输出,从 current_step 继续

## 恢复后的约束(继承 diagnose,不降低)

resume 只负责**恢复现场**——恢复后继续的是 `/diagnose` 的完整诊断循环(步骤 2-6),**不是更松的模式**。续接中以下 diagnose 约束**同样生效**(完整定义以 `skills/diagnose/SKILL.md` 为准,此处只列续接时最易被丢失的):

- **severity 闸门**:`data-loss-risk` 不给 fix,先停/保留现场/通知 owner;`service-affecting` 标 `fix_side_effects`。
- **命中输出格式 + 强度标注**:结构化推理链 + `已验证/推测/数据` + 分数校准,别甩一句 fix。
- **经验证后给 fix**:对照已提供信息验证 diagnosis checks,缺就问;`fix_on_mismatch` 带 rollback。
- **版本软匹配**:compat 不符只降排序分数,不硬排除。
- **证据落盘铁律**:用户证据完整落 `traces/evidence/<session_id>/`,不写摘要/指纹;每次写 trace 刷新顶层 `updated_at`。
- **深度排查**:Tier 3 / 源码分析一律走 `scripts/src_fetch.py`(复用、不自行 clone)。
- **误诊归因**:反馈 not_resolved/partial → 读 trace 判 case_error/execution_error。
- **连续失败 ≤2**:两次未解决转人工,不连续试第三个。
- **trace 边界**:续接后同样别把流程/设计讨论写进本 trace(走 `_evnote.md`)。
- **检索面**:若续接中需重新路由/加载(如 active_case 丢失),照 diagnose 的 tier1 / 步骤 2 收尾的先验查询 / 两阶段 tier2 / 阶段 2.5 流程执行——那是续接中必要的重新定位,不是"回到起点"。

> 单一数据源纪律:上表是"易丢项清单",**权威定义仍在 diagnose**;两者冲突时以 diagnose 为准,并在 diagnose 同步修正。

## 不要做

- 不要从头重新收集症状——state 文件里都有
- 如果 `session_id` 和当前不匹配,提示"该问题可能已被其他人接手——是否继续?"(并发检测,脆弱机制,只作提示不硬阻塞)
- **不要在这份 trace 里记录本 resume 期间发生的流程/设计讨论**(与 diagnose 的"trace 边界"一致——那是自演进信号,走 EV card / 自演进通道,不污染本问题的诊断 trace)。`resume` 事件只承载诊断状态(恢复到哪步、待办什么),不掺流程改进内容
- 续接中若需源码分析,**用 `scripts/src_fetch.py <repo> --ref <tag> --verify "<签名>"`**(缓存按版本平铺在 `src-code/<org>/<repo>/<tag>/`、缓存根在主检出跨 worktree 共读;`--list-versions` 看本地已有版本,`--list` 看已知仓库与 host;仓不在已知表时用 `--list-orgs`、`--list-org-repos` 找),不自行决定 clone 到哪、不重复拉取。**退出码即契约**:`0` = 该版本已产出并核对通过(带 `--verify` 时签名也命中;stdout 末行 = 路径);`3/4/5` = 没拿到(tag 名不对 / 拉取失败 / 本地目录核对不通过);`6` = 拿到了但签名没命中,不能证明是它——非零就别拿本地其他版本的目录去读,也不用 web 搜索代替源码

## 状态文件生命周期

case 标 `resolved`/`escalated` 时**留在 `traces/` 原位**(用 `status` 字段标记闭环,**不挪去 `postmortems/history/`**——诊断面板与 `ascend_trace_status` 都只读 `traces/`,挪走会看不到/打不开)。`traces/` 持有全部诊断记录(进行中 + 已闭环),**判"可续接"看 `status`**:只把 `in_progress`/`feedback_pending` 的当活跃可续接;`resolved`/`escalated` 的只作参考不可续接(不再提示"续接")。**trace 历史不删**——它是路由准确率、执行保真度等指标的数据源(见 docs/guide/metrics.md)。`postmortems/` 只放知识 postmortem 工件(.md,Tier 3),不是 trace 的归档处(trace 是 gitignored 机密记录)。

**与诊断面板的闭环**:resume 是 trace 的写入方之一——续接追加 `resume` 事件 + 刷新 `updated_at`,使该 session 在面板"更新 X 前"重置、置顶。面板"继续诊断"按钮 → 复制指令 → 本 skill 触发 → 续接写 trace → 面板刷新可见活动。任一环缺失(如续接不写 trace)闭环断,面板不反映续接。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall