home / skills / chachamaru127 / claude-code-harness / troubleshoot

troubleshoot skill

safe

This skill guides diagnostics and automatic fixes for errors and CI failures, helping you repair issues without deep technical knowledge.

npx playbooks add skill chachamaru127/claude-code-harness --skill troubleshoot

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

10.9 KB

---
name: troubleshoot
description: "Diagnosis and repair guide for errors and failures including CI. Use when user mentions something broken, errors, it doesn't work, CI failures, CIが落ちた, build errors, test failures, or pipeline issues. Do NOT load for: successful builds, new feature implementation, or reviews."
description-en: "Diagnosis and repair guide for errors and failures including CI. Use when user mentions something broken, errors, it doesn't work, CI failures, build errors, test failures, or pipeline issues. Do NOT load for: successful builds, new feature implementation, or reviews."
description-ja: "動かない？エラー？CIが赤い？診断と修復をガイド。困ったときの駆け込み寺。Use when user mentions something broken, errors, it doesn't work, CI failures, CIが落ちた, build errors, test failures, or pipeline issues. Do NOT load for: successful builds, new feature implementation, or reviews."
allowed-tools: ["Read", "Grep", "Bash"]
context: fork
argument-hint: "[build|test|runtime]"
---

# 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 |
| ランタイム | 画面が表示されない | ログ分析 |
| 環境設定 | 接続エラー | 環境変数確認 |
| **CI/CD** | CI が落ちた、パイプライン失敗 | **ci スキルに dispatch** |

> **CI/CD 問題**: CI 障害・テスト失敗・パイプライン問題を検出した場合、`ci` スキル（`skills/ci/`）に処理を委譲します。ci スキルは `ci-cd-fixer` エージェントを使用して自動診断・修正を行います。

---

## 問題別対応

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

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

1. **agent-browser を最優先で使う**（インストール: `npm install -g agent-browser`）
   ```bash
   # ページを開いてスナップショット取得
   agent-browser open https://example.com/target-page
   agent-browser snapshot -i -c

   # 要素参照でクリック・入力
   agent-browser click @e1
   agent-browser fill @e2 "test"
   ```
   - 対象URLで再現 → スナップショット/コンソールを根拠に原因を絞る
   - ソースコード（UI/状態管理/API/バリデーション）を確認して修正
   - 同じ手順で再現しないことを確認
   - 参考: `docs/OPTIONAL_PLUGINS.md`
2. **agent-browser が使えない場合のフォールバック**
   - MCP ブラウザツール（chrome-devtools, playwright）
   - 再現手順（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 で最近の変更を確認 |
| 「同じエラーが何度も」 | パターンを分析して根本対策を提案 |

---

## 診断コマンド

### クイック診断

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

### 詳細診断

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

### Claude Code 固有の診断（CC 2.1.38+）

複雑なセッション問題には `/debug` コマンドが有効です。

| 症状 | 推奨 |
|------|------|
| 「セッションがおかしい」 | `/debug` でセッション診断 |
| 「MCPが動かない」 | `/debug` で MCP 状態確認 |
| 「何度試してもダメ」 | `/debug` で詳細ログ出力 |
| 「コンテキストが変」 | `/debug` でコンテキスト情報取得 |
| 「認証エラー」 | `claude auth status` で認証状態確認 (CC 2.1.41+) |

#### 認証診断（CC 2.1.41+）

CC 2.1.41 で `claude auth` サブコマンドが追加されました:

```bash
claude auth status   # 認証状態の確認
claude auth login    # 再ログイン
claude auth logout   # ログアウト
```

API キーの問題や認証切れの診断に有用です。

#### VibeCoder 向け

```
🔍 より詳しい診断が必要な場合

「もっと詳しく診断して」と言われたら:
→ `/debug` コマンドの使用を推奨

/debug コマンドは以下を診断します:
- セッション状態
- MCP サーバー接続
- プラグイン設定
- メモリ使用状況
- エラーログの詳細

💡 使い方:
チャット欄で `/debug` と入力してください
```

#### トラブルシューティング連携フロー

```
troubleshoot スキルでの診断
    ↓
一般的な問題を自動チェック
    ↓
┌─────────────────────────────────────────┐
│  解決できた？                            │
├─────────────────────────────────────────┤
│  YES → 修正完了                         │
│  NO  → 複雑な問題の可能性               │
└─────────────────────────────────────────┘
    ↓
/debug コマンドを推奨
    ↓
セッション・MCP・設定の詳細診断
    ↓
診断結果をもとに解決策提示
```

#### `/debug` が特に有効なケース

| ケース | 理由 |
|--------|------|
| 3回修正しても解決しない | 環境設定の問題の可能性 |
| MCP ツールが応答しない | MCP サーバー接続の診断が必要 |
| セッション再開後の動作不良 | セッション状態の確認が必要 |
| 他のプロジェクトでは動く | プロジェクト固有設定の問題 |

---

## 予防的アドバイス

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

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)

Overview

This skill provides step-by-step diagnosis and repair guidance for errors, failures, and CI pipeline issues. It automatically detects common problem patterns, runs targeted checks, and recommends or executes fixes with clear prompts. Use it to triage broken builds, runtime errors, test failures, and environment problems. It delegates CI-specific remediation to the ci skill when appropriate.

How this skill works

The skill asks a brief symptom summary, runs a quick automated diagnostic (env checks, build/test runs, dependency lists), and inspects logs and LSP diagnostics to locate likely causes. It maps symptoms to categories (dependency, build, runtime, environment, CI) and proposes actions: run commands, apply fixes, or escalate. For CI/CD failures it dispatches to the ci skill which uses a ci-cd-fixer agent for deeper pipeline repair.

When to use it

When a build fails or tests stop passing
When an app shows runtime errors or UI is broken
When npm install, git, or environment setup errors occur
When CI or pipeline jobs fail or report flakes
When you need a guided, reproducible repair flow

Best practices

Describe the failing symptom briefly (what you expected vs actual) before running diagnostics
Run the quick checks first: node/npm versions, git status, last build/test logs
Provide reproduction steps, screenshots, or console logs for UI issues
Confirm before destructive fixes; automatic fixes are limited to three attempts
Commit and record changes frequently so rollbacks are easy

Example use cases

White screen in the browser after deployment — run console and build checks, use agent-browser for repro and snapshot
npm install ERESOLVE — clear cache, remove node_modules, reinstall, or pin dependency
CI pipeline failing tests — triage locally, then dispatch to ci skill for pipeline remediation
Merge conflict detected in git — show conflict hunks and offer guided resolution or auto-merge with confirmation
Intermittent test failures — run targeted tests, collect logs, and suggest flaky-test isolation

FAQ

What commands does the skill run for diagnostics?

It runs environment checks (node -v, npm -v, git status), recent build/test tails (npm run build/test | tail -20), and dependency listings (npm ls --depth=0) as a quick baseline.

Will it change files automatically?

Automatic fixes are offered for straightforward issues (like missing dependencies) but require your confirmation for destructive changes; automatic attempts are limited to three before escalation.

How are CI failures handled?

CI/CD failures are detected and delegated to the ci skill, which runs a dedicated ci-cd-fixer agent for deeper pipeline diagnostics and remediation.