orca-issue

Skill：orca-issue — インシデント対応サイクル

機能開発サイクルとの違いは、2つの厳格なゲートがあることです。再現できなければ修正しない、そして赤から緑にならなければクローズしない。この Skill は既存のツール群（impact-check、safe-change、verify-before-commit、failure-flywheel）を連携させるものであり、これらを作り直すものではありません。

WHAT

目的とコンテキスト

• 目的： インシデント（bug/regression/incident）を、証拠に基づく赤から緑への修正と、抽出した知識につなげます。順番どおりの5つのゲートを飛ばさずに進めます。
• トリガー（使用するタイミング）：
  • Bug、ランタイムエラー、regression、期待と異なる動作、本番環境の incident。
  • ユーザーが「エラーが出た」「バグがある」「動作がおかしい」「昨日までは動いていた」「このエラートレースを調べて」「/orca-issue」と言ったとき。
• 対象外： 次の場合は使用しません。新機能や新たな変更のリクエスト → propose / orca-workflow。既存のツール群（impact-check、safe-change、verify-before-commit、failure-flywheel）を作り直さないでください。連携のみ行います。インシデント対応中に周辺コードを整理しないでください。

メンタルモデル

症状 → 再現（RED、証拠）→ 根本原因（「Y のため X にある」）→ 外科的な修正 → 再現 GREEN + verify → commit → 二重の知識抽出（wiki incident + flywheel + problem-tree）。厳格なゲートは2つです。ゲート2（再現）とゲート4（赤から緑）。

入力と出力の契約

	Field	Required?	意味
In	症状	はい	何が、どこで、いつからおかしいのか。不明な場合はユーザーに尋ねます
In	ログ / screenshot / コンテキスト	いいえ	トリアージで収集します。可能であればエラーメッセージを原文のまま記録します
Out	再現	はい	スクリプトまたはテスト + 証拠として保存した RED の出力
Out	修正 + 再現 GREEN + verify pass	はい（再現できない場合を除く）	verify-before-commit を通して commit
Out	wiki incident ページ	はい	llmwiki/wiki/sources/ — 症状、根本原因、修正、commit と再現を示す ## Origin
Out	failure-flywheel の記録 + problem-tree のノード	はい（プロジェクトに problem-tree がある場合）	次回に備える防護策

「完了」= 再現が GREEN + verify pass + commit + 知識抽出（wiki + flywheel）。

ルールと機能

• RULE-01 (MUST)：再現できなければ修正しない — すべての修正は、保存された RED の証拠まで追跡できなければなりません。再現のない修正は推測による修正であり、差し戻されます。
• RULE-02 (MUST)：GREEN にならなければクローズしない — エージェントの言葉は証拠ではありません。再現が GREEN になり、verify pass となった場合にのみクローズできます。
• RULE-03 (MUST)：外科的に修正する — ステップ3で範囲を特定した箇所だけを変更します。近くのコードを「整理したい」と思っても、メモにとどめ、インシデント対応中には整理しないでください。
• RULE-04 (MUST)：知識抽出は必須であり、礼儀ではありません — wiki + flywheel を記録するまで、対応は完了していません。これにより、今日のエラーが明日の防護策になります。
• RULE-05 (SHOULD)：深刻なインシデントで複数の人やエージェントが必要な場合は、ディスパッチのため orca-workflow にエスカレーションします。ただし、ゲート2と4は引き続き適用されます。
• RULE-06 (MUST)：推測する前に、エラーメッセージを原文のまま読む（superpowers systematic-debugging）— エラーメッセージとスタックトレースは、最も手軽に得られる事実です。エラーを原文のまま引用しないトリアージは、推測にすぎません。
• RULE-07 (MUST)：仮説は1つずつ検証する — 1回のサイクルで変更するのは1つだけにし、そのたびに再現を実行します。複数のものを同時に変更すると（shotgun-fix）、GREEN になっても理由がわかりません。
• RULE-08 (MUST)：修正に3回連続で失敗したら停止し、アーキテクチャの範囲を疑う — 同じ規模で4つ目の修正を試してはいけません。より大きな仮説（レイヤー違い、コンポーネント違い、基礎となる前提の誤り）を立てて、ステップ3に戻ります。
• 機能：ログとコードの読み取り、場所の特定（code-graph、impact-map、VCS 履歴）、ローカルテストの実行、safe-change のフローによるコードの変更、wiki と failure ledger の記録。デプロイは行いません。

失敗時の境界

• 症状が不明確 → clarify（ユーザーに質問）し、推測しないでください。
• 再現できない（flaky/heisenbug）→ 修正をblockedにします。試した条件を記録し、監視モード（ログ/probe の追加）に切り替えます。
• 修正後も再現が RED → 未完了です。ステップ3に戻ります。
• 修正に3回連続で失敗 → 停止し、アーキテクチャの範囲を疑います。同じ規模で4つ目の修正を試さないでください。
• 深刻なインシデントで複数の人やエージェントが必要 → orca-workflow にエスカレーションします（ゲート2と4は引き続き適用）。

HOW

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	症状、ログ	トリアージ：症状を1～2文で書き写し、エラーを原文のまま抜き出し、重大度を分類	症状＋重大度	不明確 → user に質問
W02	deterministic	症状	再現優先 GATE：スクリプト／テストを作成し、実行して赤になることを確認し、保存	保存済みの赤い再現テスト	再現できない → B01
W03	judgment	再現テスト、code-graph、impact-check、git	原因を絞り込む	「Yのため、根本原因はXにある」	—
W04	effect	根本原因	safe-change を通じて修正し、再現テスト＋プロジェクトのテスト＋verify-before-commit を再実行	再現テストが緑、コミット	まだ赤 → W03；3回失敗 → B02
W05	effect	コミット、再現テスト	二重の知見化：wiki incident ＋ failure-flywheel ＋ problem-tree	wiki ページ、記録、ノード	知見化が未完了なら作業も未完了

各ステップの詳細（W01～W05 の信頼できる情報源）— 順番どおりに実行する5つのチェックポイント。飛ばしてはいけません。

1. トリアージ — 症状を1～2文で書き直します（何が間違っているか、どこで確認できるか、いつからか）。ログ／スクリーンショット／背景情報を収集し、重大度を分類します（作業を妨げる／不便／見た目の問題）。症状が不明確なら user に質問し、推測してはいけません。
2. 再現優先 GATE（必須チェックポイント #1） — エラーを再現するスクリプト／テストを作成し、赤（失敗）の結果が出るまで実行して、証拠として保存します（テストファイルまたはスクリプト＋出力）。赤い再現テストがなければ、ここで停止します。原因について議論せず、修正もしません。エラーを再現できない（flaky/heisenbug）場合は、試した条件を明記して監視モードに移行し（ログ／プローブを追加）、当てずっぽうで修正しません。
3. 原因の絞り込み — やみくもに grep するのではなく、位置を特定するツールを使います。code-graph（get_callers／get_symbol_context）、impact-check で疑わしい領域に依存する箇所をマッピングし、時間経過による regression が疑われる場合は git bisect／git log を使います。結果は「Yのため、根本原因はXにある」という1文にまとめます。
4. 赤→緑の修正（必須チェックポイント #2） — safe-change を通じて修正します（共有コードの場合は、先に caller をマッピングします）。絞り込んだ領域だけを外科的に修正します。ステップ2の再現テストを再実行し、赤 → 緑に変わることを確認します。プロジェクトに既存のテスト／verify があれば、追加で実行します。最後に verify-before-commit で確定します。再現テストがまだ赤なら未完了です。ステップ3に戻り、「たぶん直ったはず」で済ませてはいけません。
5. 二重の知見化 — コミット後に、(a) llmwiki/wiki/sources/ に incident の wiki ページを作成します（症状、根本原因、修正を記載し、コミットと再現テストを指す ## Origin を付けます）。(b) failure-flywheel に記録し、同じエラーがしきい値に達したら rule／skill を自動提案できるようにします。(c) プロジェクトに problem-tree（llmwiki/html/problem-tree.html または fdk-problem-tree.html）がある場合は、対応するノードを追加／反転します。

分岐

ID	Kind	Guard	挙動	Skip / failure	Rejoin
B01	recovery	エラーを再現できない（flaky/heisenbug）	試した条件を明記して監視モードに移行し（ログ／プローブを追加）、当てずっぽうで修正しない	赤い再現テストがなければ W03/W04 に進まない	新しい情報とともにエラーが再発したら W02
B02	recovery	修正が3回連続で失敗	停止し、アーキテクチャの範囲を疑います。より大きな仮説（レイヤー違い、コンポーネント違い、基礎となる前提の誤り）で原因の絞り込みに戻ります	同程度の修正を4回目も試さない	W03
B03	conditional_required	多くの人／エージェントが必要な重大インシデント	orca-workflow にエスカレーションして dispatch	チェックポイント2と4は引き続き必須	W04
B04	capability_optional	プロジェクトに problem-tree（llmwiki/html/problem-tree.html または fdk-problem-tree.html）がある	W05 で対応するノードを追加／反転	なければ → スキップ	W05

検証と停止条件

チェックポイント2と4は実行して確認します。修正前に再現テストが赤、修正後に緑となることを、既存のテスト／verify と合わせて確認します。エージェントの発言は証拠ではありません。知見化が完了したら停止します。上限：修正が3回連続で失敗したら → B02。

例

• 成功例：「昨日から approve が固まる」→ タイムアウトエラーを原文のまま抜き出してトリアージ → 再現テストが赤 → git bisect で lock の変更コミットを特定 → safe-change で修正 → 再現テストが緑＋verify-before-commit → llmwiki/wiki/sources/ に incident ページ＋failure-flywheel に記録。
• **境界／失敗例：**エラーが50回に1回しか起きず、再現できない → 修正せず、試した条件を記録し、ログ／プローブを追加（B01）。
• **境界例：**user が「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.