orca-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: orca-issue — vòng xử lý sự cố

Skill: orca-issue — 事故处理流程

Khác vòng làm-tính-năng ở hai chốt cứng: không tái hiện được thì không sửa, và không đỏ→xanh thì không đóng. Skill này điều phối đồ nghề đã có (impact-check, safe-change, verify-before-commit, failure-flywheel) — không làm lại chúng.

与功能开发流程的区别在于两个硬性关卡：无法复现则不得修复，以及未实现红→绿则不得关闭。本 Skill 负责协调已有工具（impact-check、safe-change、verify-before-commit、failure-flywheel），不会重复实现这些工具。

WHAT

Purpose và context

Purpose 与 context

Purpose: đưa một sự cố (bug/regression/incident) từ triệu chứng tới fix có bằng chứng đỏ→xanh và tri thức được distill, qua 5 chốt tuần tự không nhảy cóc.
Trigger (when to use):
- Bug, lỗi runtime, regression, hành vi sai so với mong đợi, incident production.
- User nói: "lỗi rồi", "bị bug", "chạy sai", "hôm qua còn chạy", "trace lỗi này", "/orca-issue".
Non-goals: KHÔNG dùng khi: yêu cầu tính năng/thay đổi mới →
```
propose
```
/
```
orca-workflow
```
. Không làm lại đồ nghề có sẵn (impact-check, safe-change, verify-before-commit, failure-flywheel) — chỉ điều phối. Không dọn code lân cận trong vòng sự cố.

Purpose： 通过 5 个不可跳跃的顺序关卡，将一个事故（bug/regression/incident）从症状推进到具有红→绿证据的修复，并完成知识 distill。
Trigger（何时使用）：
- Bug、runtime 错误、regression、行为与预期不符、生产事故。
- 用户说：“出错了”“有 bug”“运行不对”“昨天还能运行”“追踪这个错误”“/orca-issue”。
Non-goals： 以下情况不得使用：要求新增功能或进行新变更 →
```
propose
```
/
```
orca-workflow
```
。不重复实现已有工具（impact-check、safe-change、verify-before-commit、failure-flywheel），只负责协调。事故处理期间不清理周边代码。

Mental model

triệu chứng → repro ĐỎ (bằng chứng) → root cause ("nằm ở X vì Y") → fix surgical → repro XANH + verify → commit → distill kép (wiki incident + flywheel + problem-tree)

. Hai chốt cứng: chốt 2 (repro) và chốt 4 (đỏ→xanh).

症状 → repro 红（证据）→ root cause（“位于 X，因为 Y”）→ surgical fix → repro 绿 + verify → commit → 双重 distill（incident wiki + flywheel + problem-tree）

。两个硬性关卡：关卡 2（repro）和关卡 4（红→绿）。

Input và output contract

Input 与 output contract

	Field	Required?	Ý nghĩa
In	triệu chứng	có	cái gì sai, thấy ở đâu, từ bao giờ; chưa rõ → hỏi user
In	log / screenshot / bối cảnh	không	thu ở triage; error message nguyên văn nếu có
Out	repro	có	script/test + output ĐỎ đã lưu làm bằng chứng
Out	fix + repro XANH + verify pass	có (trừ nhánh không tái hiện được)	commit qua `verify-before-commit`
Out	trang wiki incident	có	`llmwiki/wiki/sources/` — triệu chứng, root cause, fix, `## Origin` trỏ commit + repro
Out	record failure-flywheel + node problem-tree	có (problem-tree nếu dự án có)	rào chắn cho lần sau

"Xong" = repro xanh + verify pass + commit + distill (wiki + flywheel).

	Field	Required?	含义
In	症状	是	哪里不对、在哪里发现、从何时开始；尚不明确 → 询问用户
In	log / screenshot / 背景	否	在 triage 阶段收集；如有，保留原始 error message
Out	repro	是	script/test + 已保存的红 output，作为证据
Out	fix + repro 绿 + verify pass	是（无法复现的分支除外）	通过 `verify-before-commit` 提交
Out	incident wiki 页面	是	`llmwiki/wiki/sources/` ——记录症状、root cause、fix； `## Origin` 指向 commit + repro
Out	failure-flywheel 记录 + problem-tree 节点	是（项目包含 problem-tree 时）	为下一次故障设置防护

“完成” = repro 绿 + verify pass + commit + distill（wiki + flywheel）。

Rules và capabilities

Rules 与 capabilities

RULE-01 (MUST): Không repro, không sửa — mọi fix phải truy được về một bằng chứng đỏ đã lưu. Fix không có repro là fix mò, bị trả lại.
RULE-02 (MUST): Không xanh, không đóng — lời agent không phải bằng chứng; chỉ repro chuyển xanh + verify pass mới được đóng.
RULE-03 (MUST): Surgical — chỉ chạm vùng đã khoanh ở bước 3; thấy code lân cận "muốn dọn" thì ghi chú, không dọn trong vòng sự cố.
RULE-04 (MUST): Distill là bắt buộc, không phải lịch sự — vòng chưa xong khi chưa ghi wiki + flywheel; đây là cách lỗi hôm nay thành rào chắn ngày mai.
RULE-05 (SHOULD): Sự cố nặng cần nhiều người/agent → escalate sang
```
orca-workflow
```
để dispatch, nhưng các chốt 2 và 4 vẫn giữ nguyên.
RULE-06 (MUST): Đọc thông báo lỗi NGUYÊN VĂN trước khi đoán (superpowers systematic-debugging) — error message + stack trace là dữ kiện rẻ nhất; triage mà chưa trích nguyên văn lỗi là đang đoán.
RULE-07 (MUST): Một hypothesis một lần — mỗi vòng chỉ đổi MỘT thứ rồi chạy lại repro; đổi nhiều thứ cùng lúc (shotgun-fix) thì xanh cũng không biết vì sao xanh.
RULE-08 (MUST): 3 fix liên tiếp thất bại → dừng, nghi ngờ TẦM kiến trúc — không thử fix thứ 4 cùng cỡ; quay lại bước 3 với giả thuyết to hơn (sai tầng, sai component, sai giả định nền).
Capabilities: đọc log/code, định vị (code-graph, impact-map, lịch sử VCS), chạy test cục bộ, ghi code qua luồng safe-change, ghi wiki + ledger failure. Không deploy.

RULE-01 (MUST)：没有 repro，就不修复——每个 fix 都必须能追溯到一份已保存的红色证据。没有 repro 的 fix 属于盲猜，会被退回。
RULE-02 (MUST)：没有变绿，就不关闭——Agent 的话不是证据；只有 repro 转为绿色且 verify pass 后才能关闭。
RULE-03 (MUST)：Surgical——只修改步骤 3 已划定的区域；如果发现周边代码“想清理”，只做记录，不在事故处理期间清理。
RULE-04 (MUST)：Distill 是强制要求，而非礼貌性步骤——未写入 wiki + flywheel 前，事故处理流程就没有完成；这是将今天的错误转化为明天防护措施的方式。
RULE-05 (SHOULD)：重大事故需要多人或多个 Agent → escalate 至
```
orca-workflow
```
进行 dispatch，但关卡 2 和关卡 4 仍然保持不变。
RULE-06 (MUST)：在猜测前阅读原始错误消息（superpowers systematic-debugging）——error message + stack trace 是成本最低的数据；triage 时未提取原始错误，就等同于猜测。
RULE-07 (MUST)：每轮只验证一个 hypothesis——每轮只改变一项内容，然后重新运行 repro；同时修改多项内容（shotgun-fix），即使最终变绿，也无法判断变绿的原因。
RULE-08 (MUST)：连续 3 次 fix 失败 → 停止，怀疑架构层级——不要尝试第 4 个同等规模的 fix；返回步骤 3，采用更大的 hypothesis（层级错误、component 错误或基础假设错误）。
Capabilities：读取 log/code、定位（code-graph、impact-map、VCS 历史）、运行本地测试、通过 safe-change 流程写入代码、编写 wiki + failure ledger。不得 deploy。

Failure boundaries

Triệu chứng chưa rõ → clarify (hỏi user), không đoán.
Không tái hiện được (flaky/heisenbug) → blocked cho việc sửa: ghi điều kiện đã thử, hạ xuống chế độ giám sát (thêm log/probe).
Repro còn đỏ sau fix → chưa xong, quay lại bước 3.
3 fix liên tiếp thất bại → dừng, nghi tầm kiến trúc, không thử fix thứ 4 cùng cỡ.
Sự cố nặng cần nhiều người/agent → escalate
```
orca-workflow
```
(chốt 2 và 4 giữ nguyên).

症状尚不明确 → clarify（询问用户），不得猜测。
无法复现（flaky/heisenbug）→ 阻止修复：记录已尝试的条件，降级到监控模式（添加 log/probe）。
修复后 repro 仍为红色 → 尚未完成，返回步骤 3。
连续 3 次 fix 失败 → 停止，怀疑架构层级，不尝试第 4 个同等规模的 fix。
重大事故需要多人或多个 Agent → escalate
```
orca-workflow
```
（关卡 2 和 4 保持不变）。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	triệu chứng, log	Triage: chép triệu chứng 1–2 câu, trích lỗi nguyên văn, phân mức	triệu chứng + mức	chưa rõ → hỏi user
W02	deterministic	triệu chứng	Repro-first GATE: viết script/test, chạy ra ĐỎ, lưu	repro đỏ đã lưu	không tái hiện → B01
W03	judgment	repro, code-graph, impact-check, git	Khoanh vùng	"root cause nằm ở X vì Y"	—
W04	effect	root cause	Fix qua `safe-change` , chạy lại repro + test dự án + `verify-before-commit`	repro XANH, commit	còn đỏ → W03; 3 lần fail → B02
W05	effect	commit, repro	Distill kép: wiki incident + failure-flywheel + problem-tree	trang wiki, record, node	chưa distill = chưa xong

Chi tiết từng bước (nguồn chân lý cho W01–W05) — 5 chốt tuần tự, không nhảy cóc:

Triage — chép lại triệu chứng bằng 1–2 câu (cái gì sai, thấy ở đâu, từ bao giờ); thu log/screenshot/bối cảnh; phân mức (chặn việc / khó chịu / thẩm mỹ). Chưa rõ triệu chứng → hỏi user, đừng đoán.
Repro-first GATE (chốt cứng #1) — viết script/test tái hiện lỗi, chạy ra kết quả ĐỎ (fail) và lưu lại làm bằng chứng (file test hoặc script + output). Chưa có repro đỏ thì DỪNG ở đây — không bàn nguyên nhân, không sửa. Lỗi không tái hiện được (flaky/heisenbug) → ghi rõ điều kiện đã thử, hạ xuống chế độ giám sát (thêm log/probe), không sửa mò.
Khoanh vùng — dùng đồ nghề định vị thay vì grep mù: code-graph (
```
get_callers
```
/
```
get_symbol_context
```
),
```
impact-check
```
để map ai phụ thuộc vùng nghi vấn,
```
git bisect
```
/
```
git log
```
khi nghi regression theo thời gian. Kết quả: 1 câu "root cause nằm ở X vì Y".
Fix red→green (chốt cứng #2) — sửa qua
```
safe-change
```
(code dùng chung thì map caller trước), surgical đúng vùng đã khoanh. Chạy lại repro ở bước 2: phải chuyển ĐỎ → XANH; chạy thêm test/verify sẵn có của dự án; chốt bằng
```
verify-before-commit
```
. Repro còn đỏ = chưa xong, quay lại bước 3 — không được "chắc là được rồi".
Distill kép — sau khi commit: (a) trang wiki incident vào
```
llmwiki/wiki/sources/
```
(triệu chứng, root cause, fix, kèm
```
## Origin
```
trỏ commit + repro); (b) record vào
```
failure-flywheel
```
để lỗi lặp đủ ngưỡng tự đề xuất rule/skill; (c) dự án có problem-tree (
```
llmwiki/html/problem-tree.html
```
hoặc
```
fdk-problem-tree.html
```
) → thêm/flip node tương ứng.

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	症状、log	Triage：用 1–2 句话复述症状，提取原始错误，划分严重级别	症状 + 级别	尚不明确 → 询问用户
W02	deterministic	症状	Repro-first GATE：编写 script/test，运行至红色并保存	已保存的红色 repro	无法复现 → B01
W03	judgment	repro、code-graph、impact-check、git	范围定位	“root cause 位于 X，因为 Y”	—
W04	effect	root cause	通过 `safe-change` 修复，重新运行 repro + 项目 test + `verify-before-commit`	绿色 repro、commit	仍为红色 → W03；失败 3 次 → B02
W05	effect	commit、repro	双重 Distill：incident wiki + failure-flywheel + problem-tree	wiki 页面、记录、节点	未 distill = 尚未完成

每个步骤的详细信息（作为 W01–W05 的事实来源）——5 个顺序关卡，不可跳跃：

Triage——用 1–2 句话复述症状（哪里不对、在哪里发现、从何时开始）；收集 log/screenshot/背景；划分严重级别（阻塞工作 / 造成困扰 / 仅影响美观）。症状尚不明确 → 询问用户，不要猜测。
Repro-first GATE（硬性关卡 #1）——编写 script/test 以复现错误，运行得到红色（fail）结果，并将其保存为证据（test 文件或 script + output）。尚未得到红色 repro 时就在此停止——不讨论根因，不进行修复。错误无法复现（flaky/heisenbug）→ 明确记录已尝试的条件，降级到监控模式（添加 log/probe），不得盲目修复。
范围定位——使用定位工具，而不是盲目 grep：code-graph（
```
get_callers
```
/
```
get_symbol_context
```
）、
```
impact-check
```
映射依赖可疑区域的关系，怀疑是时间相关的 regression 时使用
```
git bisect
```
/
```
git log
```
。结果：用 1 句话说明“root cause 位于 X，因为 Y”。
Fix 红→绿（硬性关卡 #2）——通过
```
safe-change
```
修复（涉及共享代码时先映射 caller），对步骤 3 划定的区域进行 surgical 修复。重新运行步骤 2 的 repro：必须从红色转为绿色；同时运行项目已有的 test/verify；最后通过
```
verify-before-commit
```
完成确认。Repro 仍为红色 = 尚未完成，返回步骤 3——不能以“应该没问题了”结束。
双重 Distill——commit 后执行：(a) 在
```
llmwiki/wiki/sources/
```
中创建 incident wiki 页面（症状、root cause、fix，并使用
```
## Origin
```
指向 commit + repro）；(b) 向
```
failure-flywheel
```
写入记录，使重复错误达到阈值后能够自动提出 rule/skill；(c) 如果项目包含 problem-tree（
```
llmwiki/html/problem-tree.html
```
或
```
fdk-problem-tree.html
```
）→ 添加或翻转对应节点。

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	recovery	lỗi không tái hiện được (flaky/heisenbug)	ghi rõ điều kiện đã thử, hạ xuống chế độ giám sát (thêm log/probe), không sửa mò	không có repro đỏ → không sang W03/W04	W02 khi lỗi xuất hiện lại với dữ kiện mới
B02	recovery	3 fix liên tiếp thất bại	dừng, nghi ngờ TẦM kiến trúc; quay lại khoanh vùng với giả thuyết to hơn (sai tầng, sai component, sai giả định nền)	không thử fix thứ 4 cùng cỡ	W03
B03	conditional_required	sự cố nặng cần nhiều người/agent	escalate sang `orca-workflow` để dispatch	chốt 2 và 4 vẫn giữ nguyên	W04
B04	capability_optional	dự án có problem-tree ( `llmwiki/html/problem-tree.html` hoặc `fdk-problem-tree.html` )	thêm/flip node tương ứng ở W05	không có → skip	W05

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	recovery	错误无法复现（flaky/heisenbug）	明确记录已尝试的条件，降级到监控模式（添加 log/probe），不得盲目修复	没有红色 repro → 不进入 W03/W04	当错误带着新数据再次出现时返回 W02
B02	recovery	连续 3 次 fix 失败	停止，怀疑架构层级；采用更大的 hypothesis 返回范围定位（层级错误、component 错误或基础假设错误）	不尝试第 4 个同等规模的 fix	W03
B03	conditional_required	重大事故需要多人或多个 Agent	escalate 至 `orca-workflow` 进行 dispatch	关卡 2 和 4 保持不变	W04
B04	capability_optional	项目包含 problem-tree（ `llmwiki/html/problem-tree.html` 或 `fdk-problem-tree.html` ）	在 W05 添加或翻转对应节点	不存在 → skip	W05

Validation và stopping

Validation 与 stopping

Chốt 2 và chốt 4 kiểm bằng chạy thật: repro phải ra ĐỎ trước khi sửa và XANH sau khi sửa, cộng test/verify sẵn có. Lời agent không phải bằng chứng. Dừng khi distill xong; trần: 3 fix fail liên tiếp → B02.

关卡 2 和关卡 4 必须通过实际运行来检验：修复前 repro 必须为红色，修复后必须为绿色，并且项目的 test/verify 也必须通过。Agent 的话不是证据。Distill 完成时停止；上限：连续 3 次 fix 失败 → B02。

Examples

Positive: "approve treo từ hôm qua" → triage trích lỗi timeout nguyên văn → test repro ĐỎ →
```
git bisect
```
chỉ commit đổi lock → fix qua safe-change → repro XANH +
```
verify-before-commit
```
→ trang incident trong
```
llmwiki/wiki/sources/
```
+ record failure-flywheel.
Boundary/failure: lỗi chỉ xảy ra 1/50 lần, không repro được → không sửa, ghi điều kiện đã thử, thêm log/probe (B01).
Boundary: user xin "thêm nút export" → không phải sự cố, chuyển
```
propose
```
/
```
orca-workflow
```
.

正向：“approve 从昨天起一直挂起” → triage 提取原始 timeout 错误 → test repro 为红色 →
```
git bisect
```
定位到更改 lock 的 commit → 通过 safe-change 修复 → repro 变绿 +
```
verify-before-commit
```
→ 在
```
llmwiki/wiki/sources/
```
中创建 incident 页面 + 写入 failure-flywheel 记录。
**边界/失败：**错误仅 1/50 次发生，无法复现 → 不修复，记录已尝试的条件，添加 log/probe（B01）。
**边界：**用户要求“添加 export 按钮” → 不属于事故，转交
```
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.

吸收 2026-07-17（adapt_mode: dissolve, T-260717-02）： 最后三个关卡（阅读原始错误 · 每轮只验证一个 hypothesis · 连续 3 次失败后怀疑架构）distill 自
```
obra/superpowers
```
（
```
systematic-debugging
```
— Iron Law + Four Phases）。与现有流程重复的关卡（repro-first、root-cause、红→绿）不再重复吸收。Clone 已存在于 scratchpad/superpowers。