---
name: bugfix
user-invocable: false
description: >
  問題の診断・原因分析・類似見直し・対策や再発防止の選定を行う前に起動する。
  発見工程を問わず、振り返り・WI起草・規範改訂・レビューを含む。
  不具合の有無・原因・直し方を述べるか確認で提案する前にも起動する（対処を委譲先やAWIへ委ねる場合を含む）。
---

# バグ対応

観測した不具合を、期待する契約と直接的原因を確定してから是正し、同じ原因による別の問題まで防ぐ。
未対応（ユーザー要求を満たさずに完了したもの）とデグレード（過去に成立した機能・規範の喪失）も不具合として同じ初動から扱う。
本スキルは原因分析・類似見直し・対策と再発防止の定義を所有する。呼び出す工程の文書は起動契機・入力・権限・結果の適用・記録を定め、分析方法と処置の合否は本スキルを参照する。
発話が新規要求や提案の形でも、行う作業が本スキルの対象ならその前に本スキルを適用する（単純な改善提案まで一律に不具合と扱う趣旨とは異なる）。
実装方式、計画形式、レビュー一般、pushとCI監視はそれぞれ`agent-toolkit:writing-standards`、`agent-toolkit:plan-mode`、`agent-toolkit:review-standards`、`agent-toolkit:commit`へ委ねる。

## 読込表

次の時点または条件が成立したら、その操作の前に同じ行の資料を全文読む。

| 時点または条件 | 全文読む資料 |
| --- | --- |
| 原因分析の適用条件を判定する前、対策と再発防止策を選ぶ前、類似見直しの範囲と観点を確定する前（拡張原因分析の対象外の不良を含む） | `references/root-cause-analysis.md` |
| 拡張原因分析へ進む前と、根本原因の確定に履歴・記録の探索や2系統の分析を用いる前 | `references/causal-analysis.md` |
| AWIの`## 原因分析`を起草する前と、計画ファイル（バグ）を作成する前（拡張原因分析の対象外の不良を含む） | `references/analysis-records.md` |
| 事象単位の調査を委譲する前（拡張原因分析の対象外の不良を含む） | `references/investigation-delegation.md` |
| CI失敗を扱う前 | `references/ci-failure-handling.md` |
| CI通過の確認へ入る前 | `agent-toolkit:commit`の`references/push-and-ci.md` |
| 履歴を扱う実装単位へ入る前 | `${CLAUDE_PLUGIN_ROOT}/share/exec.subagent.md` |
| 実装担当の委譲先を確定する前 | `agent-toolkit:delegation`を起動し、同スキルの`references/runtime-routing.md` |
| `agent-toolkit:writing-standards`の`references/testing.md`「分岐条件の効果の裏付け」による検証へ入る前 | 同スキルを起動し、`references/testing.md` |

対策の深さは2つの判断で決まる。1つは不在を原因へ採る前に上位規範や目的と常識から導けるかを確かめること（`references/root-cause-analysis.md`「原因分析の品質確認」）である。もう1つは条文の追加より除去・緩和・一般化を先に評価すること（`references/root-cause-analysis.md`「再発防止策」）である。

## 問題を見つけたときの対処

対処の候補は`agent-toolkit/rules/01-agent.md`「判断指針」の3段判定で選別し、構造の比較には`agent-toolkit:writing-standards`の`references/design-heuristics.md`「設計案の予備選別」を使う。

- 既存不良も原則として同じセッションで類似見直し・再発防止策まで完遂する。先送りと担当外不良は`agent-toolkit/rules/01-agent.md`「完遂と先送り」、実行中のスキル固有の扱いはその手順（`agent-toolkit:process-wi`など）に従う。拡張原因分析・類似見直し・再発防止策のいずれかを要する調査は`${CLAUDE_PLUGIN_ROOT}/share/defect-investigation.parent.md`へ委譲し、修正は見つけたエージェントが返却された対策で行う。根本原因と類似見直しの母集団を自ら確定でき、その全対象と再発防止策をその場で処置できる不良はその場で直す
- 続行を妨げない不自然さ・非効率・反復は即時是正から外し、メインは`agent-toolkit/share/rules-main.md`「作業中の改善点の報告」、委譲先は`agent-toolkit/share/rules-subagent.md`「返却と終端」の`気付いた改善点:`で扱う
- 完成条件外のエンドユーザー向けの不足は`agent-toolkit:user-confirmation-and-report`の`SKILL.md`「認可を要する操作」で判定する。文書を機能の制約へ合わせた場合も欠けた機能を判定し、新しい挙動の追加は同書「確認を要する事項」へ送る
- 終了コード0でも警告は意味を確かめる。未適用・未完了を示す警告には対処し、無関係と判断した警告は根拠を報告へ残す
- ユーザーが示した要件を変える変更と、「認可を要する操作」に当たる対処は合意を得てから着手する。手段の選択は`agent-toolkit:user-confirmation-and-report`「確認要否の判定」で決め、内部実装に閉じる対処は自律的に完遂する
- フック・ツール・実行環境の通知が担当外の対象、実行できない処置、実在しない前提を示した場合は、通知への応答とは別に通知機構の欠陥として処置する（同一セッションでの是正、`agent-toolkit:wi-standards`に従うAWI投入の提案、同じ欠陥を扱う未終端WIの参照のいずれか）

## 適用手順

事象がWI処理の工程や運用に関わる場合は、対策を選ぶ前に`agent-toolkit:workflow-overview`を起動する。

計画、実装、レビュー、CI失敗のいずれでも「初動と拡張原因分析の判定」から始め、読込表に従って参照資料へ進む。
文書・規範・出力文面を変える対策を提案または委譲する前は、`agent-toolkit:writing-standards`を起動し、受け取る主体が観測できる条件で方向を評価する。

## 初動と拡張原因分析の判定

- 処置案を検討する前に、事象、実際の結果、発生条件、期待する契約を確定し、次に直接的原因、作り込み要因、見逃し要因、根本原因、類似見直しの母集団を確定する。対策・横展開処置・再発防止策はその後に選ぶ。確定の基準は後続の各節が定める
- 対処をAWIの投入で終える場合も、投入前に本節を完遂する（投入前の確定事項は`agent-toolkit:wi-standards`の`### 起草完了の条件`）
- 問題をQに影響する問題とC・Dだけの問題へ分け、結果と根拠を原因分析の記録へ残す（定義と効果は`references/root-cause-analysis.md`「QとC・Dの区別」）
- 全ての問題で根本原因（誤りを成立させた構造・判断規則）を確定し、類似見直しの母集団、処置の階層、再発防止策を根本原因から導いて、変更範囲を検証する。基準は`references/root-cause-analysis.md`の「類似見直し」「処置の階層」「再発防止策の必須性」「類似見直しと再発防止の完了」が定める。拡張原因分析の要否は資料探索と分析の深さだけを決め、母集団と再発防止の要否を変えない
- 直接的原因を確定したら、拡張原因分析の要否を判定する。判定材料は対象判断を記録した計画・設計文書、当時の指示・契約、その判断を導入した変更履歴とし、材料の有無を確定できなければ拡張原因分析へ進む
- 拡張原因分析の条件: 計画または設計の時点で判断材料が揃っており、適切に判断していれば回避できた事象。機能的な実害の有無を問わない。push後のCI失敗は、自セッション帰属か帰属未確定なら自明な単純失敗も含める。条件に当たらない事象でも、根本原因の確定に履歴や記録の探索、2系統の分析が必要なら同じ工程を用いる。進む場合は`references/causal-analysis.md`に従う
- 類似原因や工程の反復は、実在する箇所を特定して判断する
- ユーザー自身の秘匿値がセッション記録・ツール出力へ露出した事象は、`agent-toolkit/rules/01-agent.md`「完遂と先送り」の扱い（事実の簡潔な報告と関連作業の継続）で終え、露出だけを理由に原因分析・類似見直し・再発防止策を選ばない。ユーザーが過剰反応自体の是正を求めた場合はその要求を処理する
- 同種の問題が反復する場合は`references/root-cause-analysis.md`「規範の前提の再検討」「反復した指摘の原因判定」を適用し、統治する規範の条文も分析対象に含める

## 直接的原因と事象時点の確定

- 事象・結果・発生条件は再現・ログ・実装から確定する。期待する契約は目的を定める仕様・設計記録・規範から確定し、実装自身の前提や文言は比べられる側として扱う
- 欠陥候補は、意図された実装、計測の誤り（標本数・単位・計算順序、計器が名称の示す量を測っているか）、ノイズや相関の取り違え、局所だけを見た評価を反証してから確定する。観測対象を生成・更新する全書込処理の入出力と正常系1件を、呼び出す側を含めて復元する（努力目標）
- 方針と実態の矛盾は、適用範囲・時点・実態の生成手順を確かめる。対象の存否は実装や設定から確定し、明文化されたプロジェクト方針は実態より優先する。複合条件は要素に分けて解消し、作成主体は原因の特定に必要な場合だけ調べる
- 処理の不成立では、制御の未到達と到達した処理の失敗を分ける。診断だけで発生位置を推定せず、実際の起動条件と成功・失敗の記録を比べ、差が現れた位置を同じ条件で再現する
- 直接的原因は、候補の機構だけを変えた対照で事象が変わることを観測して確定する
- 推定として扱う値: 相関だけの候補、条件を満たさない比較群を欠く集計、測定対象との対応を生成処理・公式資料・構造定義で確かめていない値、他の条件（時刻・負荷・準備状態など）も異なる比較、単独実行の成功や高負荷だけを根拠にした競合の候補。直接的原因の確定には推定以外の観測を使う
- 可変値の事象時点: 設定、依存版、外部状態、規範・スキル・手順の条文などを原因へ用いる場合（条文の未適用・欠落を述べる場合を含む）は、事象時点にも同じ形で適用されていたことを履歴か当時の記録で確かめる。確かめていない候補は推定とする
- 対策は直接的原因の機構を共有する対象全体へ適用し、症状を観測した呼び出し元や症状の程度で狭めない。類似見直しの母集団は根本原因から導く（`references/root-cause-analysis.md`「類似見直し」）
- 排他・競合・同時更新が候補なら、絞込みとユーザー確認の前に共有状態を書き換える主体（別プロセス、ロックを取らない手動操作、別clone・別マシンなど）を列挙する。各主体とロックの共有範囲を対応付け、ロックを共有しない主体は候補に残す
- 上流の挙動・変更が候補なら、公式資料・ソース差分・提供元Issueの一次情報で確かめる（実装読解と実機再現は補完）。内部名だけでなく機能の説明と公開資料の用語でも探す。回避処理を採用する場合は、既知の回避策・提供元の見解を採用するか、採らない理由を記録する

## 対策の選定

原因確定後に、原因となる機構・製品の公開機能と設定を公式資料と対象実装から調べ、原因に作用する案を先に列挙する。症状を抑える案も同じ階層で比べ、検出遅延・保証範囲の縮小などの品質損失を評価する。構造の除去、既存機構への統合、上流への移管も候補とし、比較は`agent-toolkit:writing-standards`の`references/design-heuristics.md`「設計案の予備選別」「案の採否と実施順の判定」に従う。
原因側の案が成立しない場合は、確かめた制約を記録する。原因が未確定なら候補を分ける調査条件を残し、対策は確定後に選ぶ。

- 採用案は原因の発生頻度・発生条件を増やさないことを先に確かめ、症状の上限を下げる効果はその後に評価する。選択肢の推奨順もこの結果で決める
- 成果物の状態を生んだ規約・手順・記載順や明示的なプロジェクト方針が原因なら、その改訂も比べる。原因を残す補償機構は、原因側の改訂が成立しない根拠を計画へ記した場合に選ぶ（努力目標）
- 元の不成立と回復に要した操作を分けて分析する。仕事量・発生源・原因への効果は、正常終了や復旧とは別に根拠を示す
- 解除条件のある暫定回避を採用したら、正式対応の対象・解除条件・復帰後の結果を`agent-toolkit:wi-standards`の通常の投入手順で保存済みAWIへ接続する（既存項目が覆えば再利用）。時間経過・外部公開待ちには同スキル「着手不能要因の分類」の冷却期限を設定し、公開日が不定なら次の再確認時点を選ぶ。期限到来と解除条件の成立は別に判定する。正式対応を要しない恒久仕様は対象外

本節は計画・実装・CI修正・確認の各工程に適用し、確認での提示方法は`agent-toolkit:user-confirmation-and-report`の`references/choice-construction.md`「候補の構成」に従う。

## テストの原因調査

テストの失敗も共通の初動から扱い、対象機能側とテスト設計・実行条件側を分けて原因を確定する。
非決定的な失敗は、待機の前提への未到達と、共有外部環境へ同時にアクセスする主体の干渉を現物で区別してから是正を選ぶ。
同期・隔離・決定論的な入力・時間上限とtrace採取の技術基準は`agent-toolkit:writing-standards`の`references/testing.md`と対象技術の資料による。

## 所要の原因調査

所要は合否と分け、保証する契約と必要な仕事量に照らして妥当性を判定する。
不要な仕事、同条件からの増大、準備・待機・外部取得・起動が支配的な結果は、条件をそろえて原因を確定してから是正を選ぶ。
欠陥の判定は順位や一律の秒数ではなく契約と仕事量の対応で行う。既存の出力で判断できる対象は再測定せず、所要出力が不足する不審な対象だけ追加で測る。

## 対策の影響範囲

対策を確定する前に、変える値や動作の直接影響範囲と別発生源（定義は`agent-toolkit:plan-mode`の`references/plan-file-standards.md`「要件・外部仕様」）を実装からたどり、追随が必要な箇所を対策へ含める。影響が局所にとどまると考えられる場合も調べる。除外・免除・解決済みとして扱う場合は、保証する側で先行動作が成立し除外する側がそれを前提としていることを双方の現物で確かめ、保証が無ければ同じ対策に含める。

## 母集団と件数を数える層

- ユーザーが観測事象の実物を示した場合は、発話の範囲語から母集団を確定してから発生条件を定め、実物は一例として扱う（範囲語と例示の優先は`agent-toolkit:user-confirmation-and-report`の`SKILL.md`「原文の保持と取り込み」）
- 症状の件数と該当対象はエンドユーザーが観測する層（描画結果・CLI出力）で数える。中間値や一部の記録で数える場合は、消費層までの変換を実装からたどり、除外した記録に該当が無いことを確かめ、数えた層を成果物へ併記する

## 外部からの不具合報告

報告が別の環境・版・過去の時点では事象が生じないと述べる場合は、その環境・版が配備する成果物へ差し替えて再現し、主張の成否と根拠を成果物へ書いてから発生条件を確定する。

## 作業途中で発見した事象

着手前の状態と現在の差分を突合し、進行中の未コミット変更で混入した事象と既存の事象を分ける。前者は現在の指示・計画・実装判断を混入原因として調べる。

## 同一症状の修正反復

同じ期待契約・症状・検証条件で2回修正しても症状が残り3回目が必要になったら、追加修正を止める。原因仮説が依存する入力、環境、実装、期待契約、検証手段、統治規範を現物で支持または反証してから修正案を選び直す。別症状・条件不一致・未適用の修正・外部基盤障害は回数に含めない。ユーザーだけが持つ値が必要な場合に限り、診断質問を1つにして尋ねる。`references/ci-failure-handling.md`の3回目以降のレビュー規定とは併用する。