バグ調査・トラブルシュートの仮説駆動ワークフロー。Use when「デバッグ」「バグ調査」「エラー解析」「動かない」。
バグ調査・トラブルシュートを支援し、根本原因の特定と修正案を提示する。 問題を切り分け、即時修正か仕様・設計の見直しかを判定し、根本的改善へ導く。
/troubleshooting TypeError: Cannot read property 'x' of undefined
/troubleshooting ログイン後にセッションが切れる問題
/troubleshooting logs/error.log
対話形式で情報を収集する。推測で埋めない。
$ARGUMENTS が提供されている場合:
$ARGUMENTS が空の場合:
「どのようなエラーや症状が発生していますか?（エラーメッセージ、スタックトレース、症状の説明）」
不明点は [NEEDS CLARIFICATION: 質問] を挿入（最大3箇所）。
問題の切り分け:
git bisect で問題導入コミットを特定詳細な分割統治パターンは references/debugging-principles.md を参照。
根本原因の特定は ultrathink で論理を丁寧に追う。
仮説検証ループ（5 Whys で深掘りしながら各層を検証）:
5 Whys で深掘り（各 Why を上記ループで検証する）:
各 Why の回答は、検証済みの事実に基づくこと。証拠なきWhyは推測の連鎖を生む。
アプローチ固着の回避: 同じツール/手法で3回進展なし → 手法を切り替える。
構造化された仮説フォーマットと認知バイアス対策は references/debugging-principles.md を参照。
調査ツールの選択:
| 調査目的 | ツール | 使い方 |
|---|---|---|
| エラーメッセージ検索 | Grep | パターンでコードベース横断検索 |
| スタックトレース追跡 | Read | 該当ファイルの前後を読む |
| 最近の変更確認 | Bash (git log/blame) | 問題箇所の変更履歴 |
| プロセス/ポート確認 | Bash (lsof -a, ps) | ランタイム状態調査 |
| シンボル参照追跡 | Serena MCP | 大規模コードベースでの影響範囲調査 |
| UI/表示問題 | playwright-cli | ブラウザ上の確認・再現 |
詳細な調査パターンは references/tool-strategies.md を参照。
ログが不足している場合: 仮説検証に必要な最小限のDEBUGログを一時追加し、修正完了後に除去。 恒久的なログ改善が必要な場合は log-designing スキルを参照。
調査中の専門スキル委譲（調査に別の専門性が必要な場合）:
| 状況 | 参照先 |
|---|---|
| ログ不足・ログ設計見直し | log-designing スキル |
| UI/表示問題の再現 | playwright-cli スキル |
| 大規模コードのシンボル追跡 | serena スキル |
Q1: 原因を理解したか?
Q2: 即時修正が可能かつ妥当か?
| 判定 | 条件 | 対応 |
|---|---|---|
| 即時修正 | コードのバグ（タイポ、null未チェック、ロジックミス） | 修正 + テスト追加 + 再現確認 |
| 仕様・前提の見直し | 仕様の誤解、設計前提の崩壊、要件の矛盾 | /discovery or /architect へエスカレーション |
| 応急処置 + 根本対応 | 即時対応が必要だが根本原因は設計にある | 応急パッチ + 根本対応を TODO/Issue に起票 |
エスカレーション判定基準（以下に該当 → 即時修正ではなく見直し/応急+根本を選択）:
エスカレーション先: /discovery（問題定義見直し）/ /architect（再設計）
修正後、必ず再現手順で問題が解消されたことを確認する。
テンプレート templates/debug-report.md を使用してデバッグレポートを作成。
再発防止の検討: