---
name: troubleshoot
description: "Guides diagnosis and resolution when problems occur. Use when user mentions 動かない, エラーが出た, 壊れた, うまくいかない, broken, doesn't work, error. Do NOT load for: 正常なビルド, 新機能実装, レビュー."
allowed-tools: ["Read", "Grep", "Bash"]
context: fork
metadata:
  skillport:
    category: worker
    tags: [troubleshoot, debug, error, diagnosis]
    alwaysApply: false
---

# Troubleshoot Skill

問題発生時の診断と解決をガイドするスキル。
VibeCoder が技術的な知識なしで問題を解決できるよう支援します。

---

## トリガーフレーズ

このスキルは以下のフレーズで自動起動します：

- 「動かない」「エラーが出た」「壊れた」
- 「うまくいかない」「失敗した」
- 「なぜ？」「原因は？」
- "it's broken", "doesn't work", "error", "why?"

---

## 概要

問題が発生したとき、VibeCoder は技術的な詳細を理解する必要はありません。
このスキルが自動的に診断し、解決策を提示します。

---

## 診断フロー

### Step 1: 症状の確認

> 🔍 **何が起きましたか？**
>
> 簡単に教えてください：
> - 「画面が真っ白」
> - 「ボタンが動かない」
> - 「データが保存されない」

### Step 2: 自動診断

```bash
# 環境チェック
node -v
npm -v
git status -sb

# エラーログ確認
npm run build 2>&1 | tail -20
npm test 2>&1 | tail -20

# 依存関係チェック
npm ls --depth=0
```

### Step 3: 問題カテゴリの特定

| カテゴリ | 症状 | 自動対応 |
|---------|------|----------|
| 依存関係 | `Cannot find module` | `npm install` |
| 型エラー | `Type error` | error-recovery agent |
| ビルドエラー | `Build failed` | error-recovery agent |
| ランタイム | 画面が表示されない | ログ分析 |
| 環境設定 | 接続エラー | 環境変数確認 |

---

## 問題別対応

### 「ボタンが動かない / フォームが送信されない / UIが崩れる」

UIの不具合は、**画面で再現して観測→修正→再検証**するのが最短です。

1. **dev-browser が導入済みなら最優先で使う**
   - 対象URLで再現 → DOM/コンソール/ネットワークを根拠に原因を絞る
   - ソースコード（UI/状態管理/API/バリデーション）を確認して修正
   - 同じ手順で再現しないことを確認
   - 参考: `docs/OPTIONAL_PLUGINS.md`
2. **dev-browser が使えない場合のフォールバック**
   - 再現手順（URL/手順/期待値/実際）
   - スクリーンショット/動画
   - コンソールログ/ネットワークログ

### 「画面が真っ白」

```
🔍 診断中...

考えられる原因:
1. ビルドエラー
2. JavaScript エラー
3. ルーティング問題

🔧 自動チェック:
- ビルドログを確認... ✅ エラーなし
- コンソールエラーを確認... ❌ エラー発見

💡 解決策:
「直して」と言ってください。自動修正を試みます。
```

### 「npm install が失敗」

```
🔍 診断中...

エラー: `ERESOLVE unable to resolve dependency tree`

🔧 解決策:
1. キャッシュをクリア
2. node_modules を再インストール

実行してもいいですか？（はい/いいえ）
```

### 「Git がおかしい」

```
🔍 診断中...

検出: マージコンフリクト発生

🔧 解決策:
1. コンフリクト箇所を表示
2. 解決方法を提案

「解決して」と言えば自動マージを試みます。
```

---

## VibeCoder向け応答パターン

### パターン1: 自動修正可能

```
⚠️ 問題を検出しました

**問題**: モジュールが見つかりません
**原因**: 依存関係の未インストール

🔧 **自動修正します**
→ `npm install` を実行中...
✅ 修正完了！もう一度試してください。
```

### パターン2: 確認が必要

```
⚠️ 問題を検出しました

**問題**: 設定ファイルの変更が必要
**影響**: 動作に影響する可能性

🤔 **確認させてください**:
設定を変更しても大丈夫ですか？

→ 「変更して」で実行
→ 「説明して」で詳細を確認
```

### パターン3: エスカレーション

```
⚠️ 複雑な問題を検出しました

**問題**: {{問題の概要}}
**試した修正**: 3回失敗

🆘 **Cursor (PM) への相談をおすすめします**

以下を Cursor に共有してください:
- エラー内容: {{要約}}
- 試した対応: {{リスト}}
- 推定原因: {{分析}}

「報告書を作って」で共有用レポートを生成します。
```

---

## よくある質問への自動応答

| 質問 | 自動応答 |
|------|----------|
| 「なぜエラーになった？」 | エラーログを分析して原因を説明 |
| 「どうすれば直る？」 | 具体的な解決手順を提示 |
| 「前は動いてたのに」 | git log で最近の変更を確認 |
| 「同じエラーが何度も」 | パターンを分析して根本対策を提案 |

---

## 診断コマンド

### クイック診断

```
「診断して」
→ 全般的な健全性チェック
→ 問題があれば報告
→ なければ「問題なし」
```

### 詳細診断

```
「詳しく診断して」
→ 依存関係チェック
→ ビルドテスト
→ テスト実行
→ 環境変数確認
→ 詳細レポート出力
```

---

## 予防的アドバイス

問題を未然に防ぐため、以下をおすすめ：

1. **定期的な `npm run build`**: 問題を早期発見
2. **こまめなコミット**: 問題発生時に戻しやすい
3. **Plans.md の更新**: 変更履歴を追跡可能に

---

## 注意事項

- 自動修正は3回まで試行
- 3回失敗したらエスカレーション
- 破壊的な操作は必ず確認を取る
- 修正履歴は session-log.md に記録

---

## 🔧 LSP 機能の活用

問題解決では LSP（Language Server Protocol）を活用して正確に原因を特定します。

### LSP Diagnostics による問題検出

```
🔍 LSP 診断実行中...

📊 診断結果:

| ファイル | 行 | メッセージ |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' は undefined の可能性があります |
| src/components/Form.tsx | 45 | 型 'string' を型 'number' に割り当てることはできません |

→ 2件の問題を検出
→ 上記が「動かない」原因の可能性が高い
```

### Go-to-definition による原因追跡

```
🔍 原因追跡

エラー: Cannot read property 'name' of undefined

追跡:
1. src/pages/user.tsx:34 - user.name を参照
2. src/hooks/useUser.ts:12 - user を返す ← Go-to-definition
3. src/api/user.ts:8 - API レスポンスが null の可能性

→ API エラー時のハンドリング不足が原因
```

### VibeCoder 向けの使い方

| 症状 | LSP 活用 |
|------|---------|
| 「動かない」 | Diagnostics でエラー箇所を特定 |
| 「どこがおかしい？」 | Go-to-definition で原因を追跡 |
| 「いつから壊れた？」 | Find-references で変更影響を確認 |

詳細: [docs/LSP_INTEGRATION.md](../../docs/LSP_INTEGRATION.md)