ch3sh-lc/myworkflow/root-cause-analysis

触发

• 必须触发：智能体闭环开发 阶段3 遇到 bug 时调用定位根因；用户直接要求"找根因 / 深度排查 / 为什么出现这个 bug / 全面扫描同类问题 / 还有没有别的地方有这问题"；同一 bug 修 2 次以上仍复发。
• 不触发：简单事实查询（直接 grep）；根因一目了然（明显语法/拼写错误）；纯功能开发/重构；已确认根因只需修（直接回 agent-dev-loop 修复）。
• 调用关系：由 agent-dev-loop 调用 → 接收其阶段 3 的 bug 上下文；用户直接调用 → 排查完成后建议交给 agent-dev-loop 修复。
• 协作级别（三级模型）：本 skill 与执行级别无关——L1 单智能体自己排完；L2 按分支/证据包横切给多个子智能体各追一条；L3 按交付物横切给各 owner。同一排查不按「先查→再验→再写报告」拆阶段接力，阶段在排查内部。

协作语义与等待纪律（硬规则）

• L3 只用于大型、长程任务：把一个超大任务切成若干相互独立的部分，模仿真人团队「各自独立工作 → 沟通 → 整合」；每个 member ≈ 一个 L2（端到端做完自己那份再整合）。不要因为“任务大”就建团——要因为“需要持续负责人与并行独立交付”才建团。
• member 之间可直接沟通：任务切分不可能一开始就完美，执行中会出现交叉、重叠、接口变化；member 之间直接协商比“上报 leader 再转发”高效。leader 只在边界冲突需裁决、目标变更、验收标准修改时介入；改了交付边界同步 leader（记录在案），不必阻塞等批准。
• member ≠ leaf：leaf 寿命绑定单个任务、只与派发者沟通、任务完成即结束；member 长期存在（睡眠/随时唤醒复用），管一个领域、可跨任务复用、可直接与其它 member/leader 沟通。
• 等待纪律（硬规则）：本 skill 涉及长命令 / 测试 / 构建 / 网络请求时，≥30 秒一律放后台任务或派 leaf，本回合内不等待（不轮询、不 sleep、不反复检查同一任务）；结果靠二次唤醒取。leader 与 member 都不阻塞。

定位

本 skill 只排查不修复。 目标：抵达真正根因（非表面症状）+ 修复前找全所有受影响位置（非只修一处）。修复执行是 myworkflow-agent-dev-loop 的职责。

核心原则

• 不找到根因不停止追问；不扫完全局不下结论。
• 每一层"因为"必须有代码/日志证据，禁止猜测。
• 直觉可能是对的，但必须经过验证。
• 完成全部 6 阶段之前，不提出修复建议。

主线（6 阶段）

阶段 1：症状收集与分类

1. 整理信息：错误原文/堆栈/复现步骤/预期vs实际/git log/环境/日志。缺失 ≥3 项 → ask_user_question 补（≤2 轮）。
2. 症状分类：🔴 崩溃异常 / 🟠 错误输出 / 🟡 性能超时 / 🟢 数据损坏 / 🔵 竞态不稳定。
3. 定位出错点：文件:行号（或 ≤3 候选），读出错代码上下文。
4. 🔵 → 启动技术 A；回归型（之前好现在坏）→ 启动技术 C。

阶段 2：5 Whys 深度追问

• 每层"因为"必须有证据；问到不能再问为止（通常 3-7 层，停止于外部系统/物理限制）；不跳过代码层、数据层。
• 区分技术根因（Why 1-4）与流程根因（Why 5+），都记录。
• 标注最深层 ← 根因：修复这一层即可消除所有上层症状。
• 出口：≥Why 3、每层有证据、已标根因层。

阶段 3：数据流逆向追踪

• 从出错点向上游绘制数据流，标注每个变换点的数据进出与检查结果。
• 用 ★★★ 标记最先出现坏数据的变换点（= 数据层根因）。
• 数据在所有变换点都正确、唯独出错点错 → 根因在出错点逻辑本身。
• 策略：正向 / 逆向（默认）/ 二分法（链路 10+ 步）/ 并行追踪（按分支/证据包横切：L2 派多个只读子智能体各追一条；L3 各 owner 分工；不按排查阶段拆）/ 插桩（→技术 B）。
• 出口：数据流图 ≥3 层、坏数据源头已标记、≥2 变换点"不确定" → 启动技术 B。

阶段 4：假设-验证循环（科学方法）

• 形成可证伪假设："如果根因是 X 位置的 Y 逻辑，则预测 Z 应成立"。
• 设计证伪实验（试图证明它错，而非证实）——抵抗确认性偏差。
• 执行：实际运行看结果，不推理。✅ 通过证伪 → 可信；❌ 推翻 → 回阶段 2/3；⚠️ 不确定 → 更精确实验。
• 推翻 ≥2 次 → 停下检查是否遗漏关键信息；≥3 次 → 升级：可能架构性问题/第三方依赖 bug/用户信息有误。
• flaky 偶发 → 技术 E 统计置信度。
• 出口：≥1 假设经证伪实验确认，≥2 个独立证据支撑（非同一文件/日志）。

阶段 5：全面性扫描

• 提取 bug 模式：函数/API 误用、数据变换缺失、条件/边界遗漏、配置/环境差异、时序/顺序依赖、校验/防护缺失。
• 多维度搜索，≥3 个维度（禁止单个 grep 就说"找全了"）：相同函数调用点 / 相同字段 / 相同逻辑结构 / 相同调用链 / 相同作者提交 / 相反对称逻辑 / 防御性缺口。
• 分类：🔴 同类确认 / 🟠 同类高概率 / 🟡 相似中概率 / 🔵 潜在低概率 / ⚫ 防御缺口。
• 出口：模式提取 ≥2 维度、搜索 ≥3 维度、全部已分类、扫描报告已生成。

阶段 6：输出与交接

• 生成报告（7 节）：症状摘要 / 根因因果链 / 数据流分析 / 根因确认（证据 + 可信度 + 专项技术使用）/ 全面扫描结果 / 交接清单 / 已知局限。
• 交回调用方：agent-dev-loop 用报告第 1/4/6 节执行修复（症状摘要 → 根因确认 → 交接清单：直接修改列表 + 回归清单）。
• 修复完成后必须经 myworkflow-real-world-verify 真实验证才算完成。

专项排查技术库（从对应阶段分叉的可选深度工具）

A. 竞态条件排查（🔵 类 / 偶发 / 并发）

1. 事件顺序重建：列出并发操作与共享资源，对比正常 vs 异常时间线，找脏读/覆盖。
2. 时序图分析：标注竞态窗口。
3. Interleaving 分析：枚举导致异常的操作交错序列。
4. 条件轮询替代盲等：任意 timeout → 用 waitFor(条件,{timeout,interval}) 而非 sleep()。见 [references/condition-based-waiting.md]。

B. 插桩调试（≥2 变换点不确定 / 多组件断裂）

1. 组件边界插桩：每边界记录「进/出」，运行一次对比哪层"出"与预期不符。
2. 二分法：长链路中间插检查点，每轮缩半。
3. 环境/配置传播验证：每层检查环境变量的接收/使用/传递。

C. Bisect 二分定位（回归型 bug）

• git bisect start → bad HEAD → good <版本> → git bisect run <验证脚本> → log → reset。
• 需 UI/特殊环境 → 手动二分：git log --oneline <good>..<bad> → 中间 commit 实测 → 缩至 1-2 提交 → git show。
• 产出：引入提交 SHA + diff + 变更行。

D. 防御性排查（外部输入 / 多层系统）

1. 穷举异常输入（null/空串/格式错/超长/XSS/路径遍历），逐层追踪处理方式。
2. 边界穷举：数值（0/-1/MAX/溢出）、集合（空/单元素/大量）、状态转移、时间边界。
3. 多层校验缺口：校验是否只在单层存在。
4. 防御纵深四层模型：L1 入口验证 / L2 业务逻辑验证 / L3 环境守卫 / L4 调试插桩——问"哪一层能阻止此 bug"，缺失则补哪层。见 [references/defense-in-depth.md]。

E. Flaky test 分析（偶发失败 / 修复置信度）

• 统计显著性判定（核心）：估算原始失败率 P_fail（≥20 次历史运行），所需连续通过 N = log(α)/log(1−P_fail)。50%→7 次；30%→13；10%→44；5%→90。禁止"跑了 3 次没挂就算过"。
• 失败模式聚类：≥2 种不同失败模式 → 多个独立根因，各自独立假设-验证。
• 环境因素隔离：时间依赖（固定时钟）/ 执行顺序（shuffle）/ 外部服务（mock）/ 随机数（固定种子）/ 异步时序 / 资源竞争 / 数据污染，逐一排除实验。

完成标志

• [ ] 6 阶段走完：因果链每层有证据；数据流坏源头已标记；≥1 假设经证伪验证 + ≥2 独立证据；扫描 ≥3 维度全分类
• [ ] 报告 7 节完整，交接清单已填写，已知局限已标注
• [ ] flaky 已按技术 E 算统计置信度
• [ ] 专项技术产出已整合进报告对应章节
• [ ] 本 skill 未产出修复代码（排查和修复分离）

证据口径映射（与 myworkflow-subagent-protocol 一致，不重复其长段）

• produced（回执）：根因报告/证据包已产出（路径 + 阶段 6 交接清单）；只有报告路径不算完成。
• verified（可复核证据）：因果链每层有证据（命令 + exit code + 日志/快照 sha256，或 runId）；超时、无输出、非空文件都不算证据。
• accepted（owner 验收）：上面「完成标志」逐条核对（6 阶段走完、≥1 假设经证伪、≥2 独立证据、扫描 ≥3 维度）后才算完成。
• 只查不修：本 skill 的 accepted 不等于修复完成，修复由 agent-dev-loop 验收。

证据纪律（反臆测 E1–E6）

排查期间先证据、后结论：报告里没有证据的句子一律视为无效，审阅者可逐条核对下面的检查点。

• E1 证据优先：涉及代码/配置/行为的判断，先读源码、文档或跑命令，不凭记忆与惯例。反例：照「通常如此」写结论；检查点：每条判断标出处（文件:行号 / 命令 + exit code）。
• E3 检查零猜想：根因必须有可复现证据——复现步骤 + 命令 + exit code 或日志片段，缺一项不算确认。不能核实的环节写「未核实 / 无法判定」，不得把推测写成根因。反例：「应该就是这里」。
• E6 交叉核对：关键事实至少取两个独立来源（源码 + 运行输出 / 文档 + 实测）；冲突以可执行结果为准，并记录冲突点与取舍理由。反例：只搜一次就定论。
• 假设-验证闭环：每个假设先写「假设（未核实）」→ 设计可证伪实验 → 用证据决定升级为结论或淘汰。反例：先定根因再挑证据；检查点：≥1 个假设被实验推翻并记录。
• E5 禁止编造：不得编造行号、日志、复现结果来凑完整报告；缺证据就留空缺并明示，宁可少一条结论。
• 证据包最小集：复现命令 + exit code + 关键日志/堆栈片段 + 文件:行号 + 环境/版本。缺项的那条结论一律降级为「未核实」。
• 报告标注：报告分「已验证（有证据）」与「未核实（待查）」两栏，未核实项同时列入已知局限，不得混写。

自检问句：这条根因我能现场复现吗？出处写了吗？两个来源对得上吗？有一项答不上，就回阶段 2/3 继续查。

E7 代价优先（谨慎执行）

• 修复建议必须含代价评估：改多少文件/模块、影响面多大、是否不可逆、回滚方式；缺一项即视为不完整。
• 高风险修复（删数据、改历史、覆盖生产文件、发布、重启）必须先备份 + 预演，不确定按高风险处理；禁止只给「这样改就好」。