Skip to content

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 重开一单——那会把它当新问题重新收集、重新路由,得到的是一份与上家不同的现场,而真实状态本来就在包里。

  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):追问“上次 的 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 时,一句话带过(几笔、最早那笔挂了多少天、"面板待办面有『补反馈』入口"),不在新诊断的开屏逐单念、也不要求他当场逐笔回报——积压时那是审讯,不是诊断。想看全量债账的人去面板;续接的职责是把手上这一单推完。

  1. 先解析 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 的旧单报「不可比」,不阻塞。

  2. 读活跃的 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 恢复,不视为异常。
  3. 恢复完整现场(读 trace 全轨迹,不只元信息):

    • 复述:session_id、status、current_step、已排除的 case(excluded_cases)、当前 active_case、last_action(上次等你做什么)
    • last_action 是当前提问:按它追问上次要的材料或决定拿到了吗;历史 evidence.missing 只作背景,不逐条重问。拿到回答后改写或清空 last_action,再继续。
    • 读 trace 数组恢复对话上下文:上次问了用户什么、用户已回答了什么、已排除哪些候选及原因(reason)——续接是接着上次的对话继续,不是从头开始(用户已提供的信息不重复要)
  4. 证据确认(跨 agent/session 的关键——agent 无法自证摘要够,必须用户裁决):

    • 复述证据清单:每个 user 事件的 content(摘要)+ evidence(内联了什么 / 引用了哪些文件 files / 来源 sources / 已知缺口 missing)
    • 问用户:"证据齐全吗?有遗漏吗?"——跨 agent 时新 agent 只见过摘要,无法判断摘要是否等于原文;missing 字段自动列出已知缺口。用户确认齐全 → 继续;用户补充 → 更新该 user 事件的 evidence 后再继续
    • 文件证据可读:evidence.files 是相对仓库路径(traces/evidence/<session_id>/),同工作区可直接读;读不到 → 问用户要
  5. 续接必写 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 写入口这一条路。

  6. 等人执行上次要求的命令并贴回输出,从 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