pillumina/ascend-sleuth / skills/resume-diagnosis
resume-diagnosis
Verified续接一个被打断的昇腾诊断 session;也用于接手另一台机器打包过来的诊断(交接包)。 读活跃的 traces/*.yaml(每个并发诊断一个文件,含 trace),复述上次停在哪一步、排除了哪些 case、当前 active case,等人贴回命令输出后继续。 也可只查一条已收尾案例的上游状态:跑 verify_upstream_outcomes 并按四种结局各说一句 (不续接、不写 trace)。 诊断被会议/上下文 compact 打断、或跨机(前一台机器上定位到一半、日志在另一台机器上)继续定位时用。
Resume Diagnosis
诊断不是连续时段——你正跑 check 命令,被拉去开会,回来 agent 上下文已被 compact,诊断链路丢失。
接手外来交接包(跨机那一半)
上家把一单打包带过来时(典型:路由与验证在前一台机器上做到一半,真正的大日志在另一台机器上),不要用 /diagnose 重开一单——那会把它当新问题重新收集、重新路由,得到的是一份与上家不同的现场,而真实状态本来就在包里。
- 落位(机械动作归脚本):
python3 scripts/import_trace.py <包.zip | 包.md | 包目录>——它校验包、落到traces/、比对知识库版本、点出缺件,并打印一屏交接简报。同名冲突时它落成<sid>-imported-<n>而不自动合并(两台机器为同一个问题各开一单是常态,要不要合并是判断,交人);同一份包重复接手它不重复落位。 - 读那句简报 +
traces/handoff/<sid>.yaml(外来单才有这个文件,是交接单的机器可读那一份):来源主机与知识库版本、交接意图(继续定位 / 复核结论 / 转上游)、上家留下的待补材料(needs)、未纳入与未内联的清单。 - 版本不一致照实说:本机知识库与上家不同时简报会点出来——
excluded_cases里的 id 可能不存在、候选排序可能不同。以本机库为准执行,发现候选集与 trace 记的对不上就如实说明,别把差异当成上家写错。 - 缺件不等于"证据已齐":简报点名的
missing(单文件 md 通道未内联的大文件、传输丢件)要在第一屏就讲清,并按needs索取;缺着它们把上家的结论当已验证继续往下推,是把"上家没验完的部分"冒充成已验证。 - 然后照下面的主流程续接——外来包接手只负责把现场放到本地,恢复现场与继续定位的规则一条不变。
只查上游(不续接)
已收尾的单不在可续接之列(status: resolved 不续接),但它可能带着上游锚点。这时要知道的是
"上游动了没有",不是"上次查到哪一步":这条路径不续接、不写 trace、不改状态,只做一次查证,
外加一句判断。
- 跑
python3 scripts/verify_upstream_outcomes.py --case <case-id>。默认就是 dry-run,不写任何文件;--case可重复,按名单一次查几条。案例没有上游锚点时它不发查询,只在汇总里报一行「不可对照」。 - 按结局说一句话,四种结局分开讲:
上游确认(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、未登录、网络失败、限流):报查不到,不猜结局。
- 结果只进对话,不进 trace:
resume事件只属于续接,这条路径一行 trace 都不写。
流程
先清反馈债——按 feedback.case 的取值分三种,别混:扫到的 state 文件里若有 feedback.outcome: pending,先看 feedback.case 是真实 case id、占位串 pending-investigation,还是空值/缺失(三种都出现过,定义见 diagnosis_state.yaml.example)。
- 真实 case id(上次命中 case 并给了可应用 fix):追问“上次 的 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 时,一句话带过(几笔、最早那笔挂了多少天、"面板待办面有『补反馈』入口"),不在新诊断的开屏逐单念、也不要求他当场逐笔回报——积压时那是审讯,不是诊断。想看全量债账的人去面板;续接的职责是把手上这一单推完。
-
先解析 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的旧单报「不可比」,不阻塞。 -
读活跃的
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 恢复,不视为异常。
- 先看有没有配套的人读报告
-
恢复完整现场(读 trace 全轨迹,不只元信息):
- 复述:session_id、status、current_step、已排除的 case(
excluded_cases)、当前 active_case、last_action(上次等你做什么) last_action是当前提问:按它追问上次要的材料或决定拿到了吗;历史evidence.missing只作背景,不逐条重问。拿到回答后改写或清空last_action,再继续。- 读 trace 数组恢复对话上下文:上次问了用户什么、用户已回答了什么、已排除哪些候选及原因(
reason)——续接是接着上次的对话继续,不是从头开始(用户已提供的信息不重复要)
- 复述:session_id、status、current_step、已排除的 case(
-
证据确认(跨 agent/session 的关键——agent 无法自证摘要够,必须用户裁决):
- 复述证据清单:每个 user 事件的
content(摘要)+evidence(内联了什么 / 引用了哪些文件files/ 来源sources/ 已知缺口missing) - 问用户:"证据齐全吗?有遗漏吗?"——跨 agent 时新 agent 只见过摘要,无法判断摘要是否等于原文;
missing字段自动列出已知缺口。用户确认齐全 → 继续;用户补充 → 更新该 user 事件的evidence后再继续 - 文件证据可读:
evidence.files是相对仓库路径(traces/evidence/<session_id>/),同工作区可直接读;读不到 → 问用户要
- 复述证据清单:每个 user 事件的
-
续接必写 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 写入口这一条路。 - 先追加一条 user 事件:
-
等人执行上次要求的命令并贴回输出,从 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)闭环断,面板不反映续接。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |