orca-issue

技能：orca-issue — 故障处理循环

与功能开发循环相比，有两个硬性关卡：无法复现就不修复，以及没有从红到绿就不关闭。此技能负责协调现有工具（impact-check、safe-change、verify-before-commit、failure-flywheel），不重复实现它们。

WHAT

用途和上下文

• 用途： 通过 5 个按顺序执行、不可跳过的关卡，将故障（bug/regression/incident）从症状推进到有红→绿证据的修复，并提炼出相关知识。
• 触发条件（何时使用）：
  • Bug、运行时错误、回归、行为与预期不符、生产环境事故。
  • 用户说：「出错了」「有 bug」「运行不对」「昨天还好好的」「追踪这个错误」「/orca-issue」。
• 非目标： 以下情况不要使用：功能需求/新增变更 → propose / orca-workflow。不要重复实现现有工具（impact-check、safe-change、verify-before-commit、failure-flywheel），只负责协调。故障处理循环中不要清理周边代码。

心智模型

症状 → 红色复现（证据）→ 根因（“问题出在 X，因为 Y”）→ 精准修复 → 绿色复现 + 验证 → 提交 → 双重提炼（wiki 事故记录 + flywheel + problem-tree）。两个硬性关卡：关卡 2（复现）和关卡 4（红→绿）。

输入和输出约定

	字段	必需？	含义
输入	症状	是	哪里出了什么问题、从什么时候开始；不清楚时 → 询问用户
输入	日志 / 截图 / 上下文	否	在分诊阶段收集；如有错误消息，须逐字记录
输出	复现	是	已保存为证据的脚本/测试 + 红色输出
输出	修复 + 绿色复现 + 验证通过	是（无法复现的分支除外）	通过 verify-before-commit 提交
输出	wiki 事故页面	是	llmwiki/wiki/sources/ — 症状、根因、修复、指向 commit + 复现的 ## Origin
输出	failure-flywheel 记录 + problem-tree 节点	是（如果项目有 problem-tree）	为下次设置防护措施

“完成” = 绿色复现 + 验证通过 + 提交 + 提炼（wiki + flywheel）。

规则和能力

• RULE-01（MUST）：无法复现，就不修复 — 每项修复都必须能追溯到已保存的红色证据。没有复现的修复就是盲目修复，会被退回。
• RULE-02（MUST）：没有转绿，就不关闭 — Agent 的说法不是证据；只有复现转绿 + 验证通过才能关闭。
• RULE-03（MUST）：精准修改 — 只修改步骤 3 中圈定的区域；发现周边代码“想顺手清理”时，记录下来，不要在故障处理循环中清理。
• RULE-04（MUST）：提炼是必需项，不是礼貌之举 — 未记录 wiki + flywheel，循环就尚未完成；这是让今天的错误成为明天防护措施的方式。
• RULE-05（SHOULD）：严重故障需要多个人员/Agent 时 → 升级到 orca-workflow 进行调度，但仍须保留关卡 2 和 4。
• RULE-06（MUST）：猜测之前先逐字读取错误消息（superpowers systematic-debugging）— 错误消息 + 堆栈跟踪是成本最低的数据；分诊时若未逐字摘录错误，就是在猜测。
• RULE-07（MUST）：每次只验证一个假设 — 每轮只改一项，然后重新运行复现；同时改多项（shotgun-fix）即使变绿，也不知道变绿的原因。
• RULE-08（MUST）：连续 3 次修复失败 → 停下，怀疑架构层级 — 不要尝试第 4 个同等规模的修复；用更大的假设回到步骤 3（层级错误、组件错误、基础假设错误）。
• 能力：读取日志/代码、定位（code-graph、impact-map、VCS 历史）、运行本地测试、通过 safe-change 流程编写代码、记录 wiki + failure ledger。不部署。

失败边界

• 症状不清楚 → 澄清（询问用户），不要猜测。
• 无法复现（flaky/heisenbug）→ 修复工作受阻：记录已尝试的条件，转为监控模式（添加日志/probe）。
• 修复后复现仍为红色 → 尚未完成，返回步骤 3。
• 连续 3 次修复失败 → 停下，怀疑架构层级，不要尝试第 4 个同等规模的修复。
• 严重故障需要多个人员/Agent → 升级到 orca-workflow（关卡 2 和 4 保持不变）。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	判断	症状、日志	分诊：用 1–2 句话抄录症状，逐字引用错误，划分级别	症状 + 级别	不清楚 → 询问用户
W02	确定性	症状	复现优先 GATE：编写脚本/测试，运行得到红色结果，并保存	已保存的红色复现	无法复现 → B01
W03	判断	复现、code-graph、impact-check、git	缩小范围	“根因在 X，因为 Y”	—
W04	执行	根因	通过 safe-change 修复，重新运行复现 + 项目测试 + verify-before-commit	复现变绿，已提交	仍为红色 → W03；失败 3 次 → B02
W05	执行	提交、复现	双重提炼：wiki 事件记录 + failure-flywheel + problem-tree	wiki 页面、记录、节点	未完成提炼 = 未完成

各步骤详情（W01–W05 的事实来源）——依次经过 5 个关卡，不可跳步：

1. 分诊 — 用 1–2 句话记录症状（什么出了问题、在哪里看到、从什么时候开始）；收集日志/截图/背景信息；划分级别（阻碍工作 / 令人困扰 / 仅影响美观）。症状不清楚 → 询问用户，不要猜测。
2. 复现优先 GATE（硬性关卡 #1） — 编写脚本/测试以复现问题，运行并得到红色结果（失败），然后保存为证据（测试文件或脚本 + 输出）。没有红色复现就停在这里——不讨论原因，不进行修复。无法复现的问题（flaky/heisenbug）→ 明确记录已尝试的条件，转为监控模式（添加日志/探针），不要盲目修复。
3. 缩小范围 — 使用定位工具，而不是盲目 grep：使用 code-graph（get_callers/get_symbol_context），用 impact-check 映射谁依赖可疑区域；怀疑是随时间出现的 regression 时，使用 git bisect/git log。结果：用一句话说明“根因在 X，因为 Y”。
4. 修复 red→green（硬性关卡 #2） — 通过 safe-change 修复（如果是共用代码，先映射调用方），精准修改已缩小范围的区域。重新运行步骤 2 中的复现：必须从红色 → 绿色；再运行项目已有的测试/验证；最后通过 verify-before-commit 确认。复现仍为红色 = 尚未完成，返回步骤 3——不能说“应该已经好了”。
5. 双重提炼 — 提交后：(a) 在 llmwiki/wiki/sources/ 中创建 wiki 事件页面（症状、根因、修复，并附上指向提交 + 复现的 ## Origin）；(b) 向 failure-flywheel 添加记录，使重复问题达到阈值后可自动提议规则/技能；(c) 如果项目有 problem-tree（llmwiki/html/problem-tree.html 或 fdk-problem-tree.html），则添加/翻转相应节点。

分支

ID	类型	条件	行为	跳过/失败	重新汇合
B01	恢复	问题无法复现（flaky/heisenbug）	明确记录已尝试的条件，转为监控模式（添加日志/探针），不要盲目修复	没有红色复现 → 不进入 W03/W04	问题再次出现且有新证据时进入 W02
B02	恢复	连续 3 次修复失败	停止，怀疑是架构层面的问题；带着更大的假设（层级错误、组件错误、基础假设错误）重新缩小范围	不要尝试第 4 次同等规模的修复	W03
B03	有条件必需	严重事故需要多人/Agent 处理	升级到 orca-workflow 进行调度	仍须遵守关卡 2 和 4	W04
B04	可选能力	项目有 problem-tree（llmwiki/html/problem-tree.html 或 fdk-problem-tree.html）	在 W05 添加/翻转相应节点	没有 → 跳过	W05

验证与停止

通过实际运行来验证关卡 2 和关卡 4：修复前复现必须得到红色结果，修复后必须得到绿色结果，并运行已有的测试/验证。Agent 的说法不是证据。提炼完成后停止；上限：连续 3 次修复失败 → B02。

示例

• 正向示例：“approve 从昨天开始就卡住了” → 分诊并逐字引用超时错误 → 测试复现得到红色结果 → git bisect 定位到修改锁的提交 → 通过 safe-change 修复 → 复现变绿 + verify-before-commit → 在 llmwiki/wiki/sources/ 中创建事件页面 + 添加 failure-flywheel 记录。
• **边界/失败：**问题只在 50 次中出现 1 次，无法复现 → 不修复，记录已尝试的条件，添加日志/探针（B01）。
• **边界：**用户要求“添加导出按钮” → 这不是事故，转到 propose / orca-workflow。

Origin

• Absorb 2026-07-17 (adapt_mode: dissolve, T-260717-02): 3 chốt cuối (đọc lỗi nguyên văn · một hypothesis một lần · 3-fail-nghi-kiến-trúc) distill từ obra/superpowers (systematic-debugging — Iron Law + Four Phases). Các chốt trùng vòng sẵn có (repro-first, root-cause, red→green) KHÔNG absorb lại. Clone sẵn trong scratchpad/superpowers.