A skill that guides diagnosis and resolution when problems occur. It helps VibeCoder solve problems without technical knowledge.
Trigger phrase
This skill is automatically triggered by the following phrases:
- "It doesn't work", "I got an error", "It broke"
- "It's not going well", "It failed"
- "Why?", "What's the cause?"
- "it's broken", "doesn't work", "error", "why?"
Overview
When a problem occurs, VibeCoder does not need to understand the technical details. This skill automatically diagnoses and presents solutions.
Diagnosis Flow
Step 1: Confirming the Symptoms
🔍 What happened?
Please tell me briefly:
- "The screen is all white"
- "The button doesn't work"
- "The data isn't saved"
Step 2: Automatic Diagnosis
# 環境チェック
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: Identifying the Problem Category
| Category | Symptom | Automatic Handling |
|---|---|---|
| Dependencies | Cannot find module |
npm install |
| Type errors | Type error |
error-recovery agent |
| Build error | Build failed |
error-recovery agent |
| Runtime | Screen doesn't display | Log analysis |
| Environment settings | Connection errors | Environment variable check |
| CI/CD | CI failed, pipeline failure | dispatch to ci skill |
CI/CD problems: If CI failures, test failures, or pipeline problems are detected,
ciskill (skills/ci/), the process is delegated. The ci skill uses theci-cd-fixeragent to perform automatic diagnosis and fixes.
Handling by Problem
"The button doesn't work / the form isn't submitted / the UI is broken"
For UI defects,reproduce and observe in the screen → fix → re-verifyis the fastest approach.
- Use agent-browser with the highest priority(Install:
npm install -g agent-browser）# ページを開いてスナップショット取得 agent-browser open https://example.com/target-page agent-browser snapshot -i -c # 要素参照でクリック・入力 agent-browser click @e1 agent-browser fill @e2 "test"- Reproduce at the target URL → narrow down the cause based on snapshots/console
- Check the source code (UI/state management/API/validation) and fix
- Confirm that it does not reproduce with the same steps
- Reference:
docs/OPTIONAL_PLUGINS.md
- Fallback when agent-browser is unavailable
- MCP browser tools (chrome-devtools, playwright)
- Reproduction steps (URL/steps/expected/actual)
- Screenshot/video
- Console logs/network logs
"The screen is all white"
🔍 診断中...
考えられる原因:
1. ビルドエラー
2. JavaScript エラー
3. ルーティング問題
🔧 自動チェック:
- ビルドログを確認... ✅ エラーなし
- コンソールエラーを確認... ❌ エラー発見
💡 解決策:
「直して」と言ってください。自動修正を試みます。
"npm install fails"
🔍 診断中...
エラー: `ERESOLVE unable to resolve dependency tree`
🔧 解決策:
1. キャッシュをクリア
2. node_modules を再インストール
実行してもいいですか？（はい/いいえ）
"Git is acting weird"
🔍 診断中...
検出: マージコンフリクト発生
🔧 解決策:
1. コンフリクト箇所を表示
2. 解決方法を提案
「解決して」と言えば自動マージを試みます。
Response Patterns for VibeCoder
Pattern 1: Automatically fixable
⚠️ 問題を検出しました
**問題**: モジュールが見つかりません
**原因**: 依存関係の未インストール
🔧 **自動修正します**
→ `npm install` を実行中...
✅ 修正完了！もう一度試してください。
Pattern 2: Confirmation needed
⚠️ 問題を検出しました
**問題**: 設定ファイルの変更が必要
**影響**: 動作に影響する可能性
🤔 **確認させてください**:
設定を変更しても大丈夫ですか？
→ 「変更して」で実行
→ 「説明して」で詳細を確認
Pattern 3: Escalation
⚠️ 複雑な問題を検出しました
**問題**: {{問題の概要}}
**試した修正**: 3回失敗
🆘 **Cursor (PM) への相談をおすすめします**
以下を Cursor に共有してください:
- エラー内容: {{要約}}
- 試した対応: {{リスト}}
- 推定原因: {{分析}}
「報告書を作って」で共有用レポートを生成します。
Automatic Responses to Common Questions
| Question | Automatic Response |
|---|---|
| "Why did it error?" | Analyze the error log and explain the cause |
| "How can I fix it?" | Present concrete resolution steps |
| "It was working before" | Check recent changes with git log |
| "The same error over and over" | Analyze the pattern and propose a fundamental fix |
Diagnostic Commands
Quick Diagnostics
「診断して」
→ 全般的な健全性チェック
→ 問題があれば報告
→ なければ「問題なし」
Detailed Diagnostics
「詳しく診断して」
→ 依存関係チェック
→ ビルドテスト
→ テスト実行
→ 環境変数確認
→ 詳細レポート出力
Claude Code-specific diagnostics (CC 2.1.49+)
For complex session issues, the /debug command is effective.
| Symptom | Recommended |
|---|---|
| "The session is acting weird" | /debug for session diagnostics |
| "MCP doesn't work" | /debug to check MCP status |
| "It fails no matter how many times I try" | /debug to output detailed logs |
| "The context is strange" | /debug to retrieve context information |
| "Authentication error" | claude auth status to check authentication status (CC 2.1.41+) |
| "The agent doesn't work" | claude agents list to check agent definitions (CC 2.1.50+) |
| "The skill operates with old content" | /clear to run and reset the skill cache (CC v2.1.63+) |
Agent diagnostics (CC 2.1.50+)
CC 2.1.50 で claude agents CLI commands have been added:
claude agents list # 登録済みエージェントの一覧
Useful for diagnosing agent spawn failures and Team initialization errors. Check this when the Implementer/Reviewer does not start during Breezing.
Authentication diagnostics (CC 2.1.41+)
CC 2.1.41 で claude auth subcommands have been added:
claude auth status # 認証状態の確認
claude auth login # 再ログイン
claude auth logout # ログアウト
Useful for diagnosing API key issues and authentication expiration.
For VibeCoders
🔍 より詳しい診断が必要な場合
「もっと詳しく診断して」と言われたら:
→ `/debug` コマンドの使用を推奨
/debug コマンドは以下を診断します:
- セッション状態
- MCP サーバー接続
- プラグイン設定
- メモリ使用状況
- エラーログの詳細
💡 使い方:
チャット欄で `/debug` と入力してください
Troubleshooting Coordination Flow
troubleshoot スキルでの診断
↓
一般的な問題を自動チェック
↓
┌─────────────────────────────────────────┐
│ 解決できた？ │
├─────────────────────────────────────────┤
│ YES → 修正完了 │
│ NO → 複雑な問題の可能性 │
└─────────────────────────────────────────┘
↓
/debug コマンドを推奨
↓
セッション・MCP・設定の詳細診断
↓
診断結果をもとに解決策提示
/debug Cases where this is particularly effective
| Case | Reason |
|---|---|
| Not resolved after 3 fix attempts | Possible environment configuration issue |
| MCP tools do not respond | Diagnosis of the MCP server connection is needed |
| Malfunction after resuming a session | Session state needs to be checked |
| It works in other projects | Project-specific configuration issue |
Preventive Advice
To prevent problems before they occur, the following is recommended:
- Regular
npm run build: Detect problems early - Frequent commits: Easy to roll back when a problem occurs
- Updating Plans.md: Make the change history trackable
Notes
- Auto-fix is attempted up to 3 times
- Escalate after 3 failures
- Always confirm before destructive operations
- Record the fix history in session-log.md
🔧 Utilizing LSP Features
For problem solving, utilize LSP (Language Server Protocol) to accurately identify the cause.
Problem detection via LSP Diagnostics
🔍 LSP 診断実行中...
📊 診断結果:
| ファイル | 行 | メッセージ |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' は undefined の可能性があります |
| src/components/Form.tsx | 45 | 型 'string' を型 'number' に割り当てることはできません |
→ 2件の問題を検出
→ 上記が「動かない」原因の可能性が高い
Cause tracing via 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 エラー時のハンドリング不足が原因
How to use it for VibeCoders
| Symptom | LSP Utilization |
|---|---|
| "It doesn't work" | Identify the error location with Diagnostics |
| "Where is it wrong?" | Trace the cause with Go-to-definition |
| "Since when has it been broken?" | Check the impact of changes with Find-references |
Details: docs/LSP_INTEGRATION.md