ysaa1/harness-workflow/diagnose

Evidence-based diagnosis

将用户描述的故障与真实环境对应，区分现象、假设、已证实原因和修复证据。不要用隐藏错误、跳过测试或扩大容错来冒充修复。阶段只在有明示理由时跳过。

流程

1. 保护现场并脱敏：捕获相关命令、cwd、环境、退出码、日志、输入和最近改动。展示前把密钥写成 <REDACTED>；回路里的凭据走环境变量，不进展示内容；采集物只引用带信号的行。
2. 先建反馈回路（闸门）：提出任何根因假设之前，先有一条命令（测试调用、脚本路径、curl 等），且已至少跑过一次（展示调用与脱敏输出），满足：

• 能变红：走真实故障路径、断言用户的原症状，修好后会变绿——「跑完没报错」不算；
• 确定：每次判决相同；偶发故障追求更高复现率（循环触发、并发、加压、收窄时间窗），不追求干净复现；
• 快：秒级而非分钟级；
• agent 可无人值守运行：必须有人参与时用结构化脚本驱动人，输出回流。

有了回路就当产品打磨：更快、信号更尖、更确定。构造手段菜单见 references/feedback-loops.md。为找 seam、搭回路读代码不受限；发现自己在回路出现前读代码编根因理论——停下，这正是本闸门要防的失败。 豁免：昂贵 GPU、线上、破坏性或外部环境确实建不出回路，或用户只授权只读诊断（不能新写脚本/测试）且现有命令无法充当回路时，明示已尝试的手段与缺口（环境访问、脱敏采集物如日志/HAR/core dump、临时埋点许可），向用户索取；可继续用既有日志、源码与配置推理，但结论一律标「未验证假设」，不得声称修复已验证。昂贵任务不为凑次数反复跑。

1. 复现并最小化：跑回路看它红；确认红的是用户描述的症状而非邻近故障（错的 bug＝错的修复）。再逐项削减输入、调用方、配置、数据与步骤，每削一项重跑，直到每个剩余元素都承重（去掉任何一个就变绿）。
2. 排序可证伪假设：动手验证前列出多个候选并排序，不锚定第一个看似合理的想法；不强制固定条数。每条写出预测——「若 X 是原因，则改 Y 会让故障消失 / 改 Z 会加重」；写不出预测的是感觉，丢弃或磨尖。排序清单展示给用户（对方常有能当场重排的领域知识），但不阻塞等待。
3. 定点埋点：每个探针对应一条预测，一次只变一个量；独立只读检查可以并行。优先调试器/REPL，其次在区分假设的边界处打日志，不「全量打日志再 grep」。调试日志统一带唯一前缀（如 [DEBUG-a4f2]），收尾一次 grep 清除。性能问题先建基线测量再二分，先量后修。
4. 修复与回归测试：在正确 seam（测试复现故障在调用现场的真实形态）上把最小化复现变成失败测试 → 看它红（红若是靠篡改代码或 fixture 强造的，先 diff 原样副本证明改动确实生效再信它）→ 授权范围内最小修复 → 看它绿 → 对未最小化的原始场景重跑第 2 步回路。只有过浅的 seam 时不硬写回归测试（假安全感）：无正确 seam 本身是发现，写进报告，作为 cleanup 环境改进候选。不要把相邻无关失败混成同一个根因。
5. 持续有信息增益且在预算内时继续。无新证据、需要外部访问或成本超出授权时说明具体缺口；不以固定三轮自动宣布阻塞。

完成与输出

完成前核对：原回路不再复现；回归测试通过（或无正确 seam 已记录）；[DEBUG- 前缀零残留；一次性原型已删除或移入明确标记的调试位置；有修复提交时被证实的假设写进 commit 信息，让下一个排障者学到。

给出故障、反馈回路命令、支持/排除的关键假设、根因或未定项、修改及验证。只读诊断可交付有边界的结论，无需强制修代码。调查中途就把回路命令、关键 dead ends、排除的假设和恢复命令记进本轨道的计划文件（或 artifacts/），不等收尾，以免会话中断后重走死路；没有计划文件时随本次报告交付，不为此新建轨道。.harness/ 只在阶段变化或交接时由本轨道 tracks/<id>.md 的 Evidence: 链接它们（写入时机见 ../writing-for-agents/references/recovery_surface_policy.md）。长调查后重读任务入口防漂移。值得复用的根因在报告里写成 lessons 候选（触发 → 坑 → 正确做法），由收尾的 cleanup 写进项目 lessons。

工作台级问题可参考 references/harness-layer-patterns.md；不要因一条命令失败就安装新工具或重建 harness。

Recommended next skill

• 原因已明但需修改：implement；修复复杂或用户要求评审：review。
• 简单修复已验证或只读诊断已交付：有 lessons 候选时交 cleanup 落笔，否则结束；无正确 seam 或回路难建暴露工作台缺口：收尾时交 cleanup 列为环境改进候选。
• 仅在实际缺口需改工作台时：harness-builder；目标改变才回 plan。