By name: troubleshoot description: >- バグ・エラー・予期しない挙動の根本原因を診断する時に使用する。 ナレッジベースを確認し、再現・切り分け・原因特定を行い、修正方針を提案する。 コードは修正しない。troubleshooter サブエージェントが使用する。 user-invocable: false allowed-tools: [Read, Glob, Grep, Bash]
トラブルシューティングワークフロー
troubleshooter サブエージェントが従う診断プロセスを定義する。
バグ・エラー・予期しない挙動に対し、再現と切り分けで根本原因を証拠付きで特定し、修正方針を提案する。
コードの修正は行わない。
フェーズ 1: 問題の把握
呼び出し元から渡された情報を整理する。
- 症状: エラーメッセージ・スタックトレース・誤った出力・ハング・リソース枯渇など。
- 再現手順: 問題を再現するコマンドや操作。
- 期待する挙動: 本来どうあるべきか。
エラーメッセージやスタックトレースがあれば、Grep で該当箇所を検索して起点を特定する。
.artifacts/project_architecture.md や関連する specification.md があれば読み込み、構造と制約を把握する。
フェーズ 2: ナレッジベースの確認
切り分けの前に、必ず既存のナレッジベースを確認する。
Glob で .artifacts/troubleshooting/*.md を一覧し、症状に合致するファイルを Read で確認する。
既知の同種事例があれば、その原因・修正方針・再発防止を活用する。見つからない場合は次のフェーズへ進む。
フェーズ 3: 再現と切り分け
- 再現: 渡された手順で問題を再現する。再現コマンドはタイムアウトや入力制限を付けて安全に実行し、 ハング・リソース枯渇を疑う場合は暴走させない（例: 短いタイムアウト・最小入力で確認する）。
- 切り分け: 問題を起こす範囲を絞り込む。二分探索的にコード・入力・設定を狭め、 最小再現条件を特定する。プロダクトコードとテストコードのどちらに原因があるかを区別する。
- 観察: ログ・出力・状態を観察し、想定との差分を記録する。
フェーズ 4: 根本原因の特定と修正方針
- 根本原因: 症状の表層ではなく、それを生む根本原因を証拠（再現・ログ・コード参照）で裏付けて特定する。 対象ファイル・行を明示する。
- 修正方針: 推奨する直し方を提案する（適用はしない）。トレードオフのある場合は代替案を併記する。
- 再発防止: 同種の問題を防ぐ観点（テスト設計・ガード・契約の明確化など）を示す。
フェーズ 5: 完了の扱い
根本原因・修正方針・再発防止・不明点が整理できた時点で本スキルの責務は完了とする。
結果ファイルへの書き出しと呼び出し元への報告は本スキルでは行わず、
呼び出し元（troubleshooter エージェント定義）が担う。
原因の候補について、以下の順でステップごとに思考を展開すること。 最終出力には含めず、内部推論として用いる。
- 症状の正確化: 観測された事実は何か（再現条件・タイミング・範囲）。
- 仮説の列挙: 原因の候補を 2〜3 個挙げる。
- 証拠との照合: 各仮説を再現・ログ・コードで検証し、支持／反証する証拠を集める。
- 根本原因の確定: 表層の症状ではなく根本原因まで遡れているかを確認し、判断根拠を一文で要約する。
- 不明点の特定: 確定できなかった点を「次の候補」として整理する。
- コードは修正しない: 本スキルは診断に専念し、プロダクトコードを変更しない。修正は呼び出し元が別途対応する。
- ナレッジベースを優先する: 切り分けの前に必ず既存の
.artifacts/troubleshooting/を確認する。 - 証拠で語る: 根本原因は証拠で裏付ける。推測は「推測」と明記し、事実と分ける。
- 根本原因まで遡る: 症状への対症ではなく、それを生む根本原因を特定する。
- 再現は安全に行う: ハングやリソース枯渇が疑われる再現はタイムアウトや入力制限を付け、暴走させない。