Troubleshoot Skill

A skill that guides diagnosis and resolution when issues occur. It helps VibeCoder resolve problems without requiring technical knowledge.

Trigger Phrases

This skill automatically activates for the following phrases:

"It doesn't work", "An error occurred", "It's broken"
"It didn't go well", "It failed"
"Why?", "What's the cause?"
"it's broken", "doesn't work", "error", "why?"

Overview

When an issue occurs, VibeCoder doesn't need to understand technical details. This skill automatically diagnoses and presents solutions.

Diagnosis Flow

Step 1: Confirm Symptoms

🔍 What happened?

Please tell us briefly:

"The screen is completely white"

"The button won't work"

"Data isn't saving"

Step 2: Automatic Diagnosis

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: Identify Problem Category

Category	Symptoms	Automatic Response
Dependencies	`Cannot find module`	`npm install`
Type Errors	`Type error`	error-recovery agent
Build Errors	`Build failed`	error-recovery agent
Runtime	Screen not displaying	Log analysis
Environment Settings	Connection errors	Environment variable check
CI/CD	CI failed, pipeline failure	Dispatch to ci skill

CI/CD Issues: When CI failures, test failures, or pipeline issues are detected, the process is delegated to the
ci
skill located at
skills/ci/
. The ci skill uses the
ci-cd-fixer
agent to perform automatic diagnosis and correction.

Issue-Specific Solutions

"Buttons won't work / Forms won't submit / UI is broken"

For UI issues, the fastest way is to reproduce and observe on the screen → fix → re-verify.

Prioritize using agent-browser (Installation:

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"

Reproduce on the target URL → Narrow down the cause based on snapshots/console logs
Check source code (UI/state management/API/validation) and fix
Verify the issue no longer reproduces using the same steps
Reference:
```
docs/OPTIONAL_PLUGINS.md
```

Fallback if agent-browser is unavailable
- MCP browser tools (chrome-devtools, playwright)
- Reproduction steps (URL/steps/expected result/actual result)
- Screenshots/videos
- Console logs/network logs

"Screen is completely white"

🔍 診断中...

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

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

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

Translated content for the above block:

🔍 Diagnosing...

Possible causes:
1. Build error
2. JavaScript error
3. Routing issue

🔧 Automatic checks:
- Checking build logs... ✅ No errors
- Checking console errors... ❌ Error found

💡 Solution:
Say "Fix it" to attempt automatic correction.

"npm install failed"

🔍 Diagnosing...

Error: `ERESOLVE unable to resolve dependency tree`

🔧 Solutions:
1. Clear cache
2. Reinstall node_modules

Can I execute these steps? (Yes/No)

"Git is behaving strangely"

🔍 Diagnosing...

Detected: Merge conflict occurred

🔧 Solutions:
1. Show conflict locations
2. Propose resolution methods

Say "Resolve it" to attempt automatic merging.

Response Patterns for VibeCoder

Pattern 1: Automatically Fixable

⚠️ Issue detected

**Problem**: Module not found
**Cause**: Dependencies not installed

🔧 **Automatic fix in progress**
→ Executing `npm install`...
✅ Fix completed! Please try again.

Pattern 2: Confirmation Required

⚠️ Issue detected

**Problem**: Configuration file needs to be changed
**Impact**: May affect functionality

🤔 **Please confirm**:
Is it okay to modify the configuration?

→ Say "Change it" to execute
→ Say "Explain it" to check details

Pattern 3: Escalation

⚠️ Complex issue detected

**Problem**: {{Issue summary}}
**Fix attempts made**: 3 failures

🆘 **Recommended to consult Cursor (PM)**

Please share the following with Cursor:
- Error details: {{Summary}}
- Attempted fixes: {{List}}
- Estimated cause: {{Analysis}}

Say "Create a report" to generate a sharing report.

Automatic Responses to Common Questions

Question	Automatic Response
"Why did I get an error?"	Analyze error logs and explain the cause
"How do I fix it?"	Present specific resolution steps
"It worked before, why not now?"	Check recent changes using git log
"I keep getting the same error"	Analyze patterns and propose root cause solutions

Diagnosis Commands

Quick Diagnosis

"Diagnose"
→ General health check
→ Report issues if any
→ Reply "No issues found" if none

Detailed Diagnosis

"Diagnose in detail"
→ Dependency check
→ Build test
→ Test execution
→ Environment variable check
→ Output detailed report

Claude Code-Specific Diagnosis (CC 2.1.49+)

For complex session issues, the

/debug

command is effective.

Symptom	Recommendation
"Session is behaving strangely"	Use `/debug` for session diagnosis
"MCP isn't working"	Use `/debug` to check MCP status
"It still doesn't work after multiple attempts"	Use `/debug` to output detailed logs
"Context is odd"	Use `/debug` to get context information
"Authentication error"	Check authentication status with `claude auth status` (CC 2.1.41+)

Authentication Diagnosis (CC 2.1.41+)

The

claude auth

subcommand was added in CC 2.1.41:

bash

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

Useful for diagnosing API key issues and expired authentication.

For VibeCoder

🔍 When more detailed diagnosis is needed

If told "Diagnose in more detail":
→ Recommend using the `/debug` command

/debug command diagnoses the following:
- Session status
- MCP server connection
- Plugin settings
- Memory usage
- Detailed error logs

💡 How to use:
Enter `/debug` in the chat box

Troubleshooting Collaboration Flow

troubleshoot skill diagnosis
    ↓
Automatic check for common issues
    ↓
┌─────────────────────────────────────────┐
│  Issue resolved?                        │
├─────────────────────────────────────────┤
│  YES → Fix completed                     │
│  NO → Possible complex issue             │
└─────────────────────────────────────────┘
    ↓
Recommend `/debug` command
    ↓
Detailed diagnosis of session, MCP, and settings
    ↓
Propose solutions based on diagnosis results

Cases Where

/debug

Is Particularly Effective

Case	Reason
Issue not resolved after 3 fix attempts	Possible environment configuration issue
MCP tools not responding	Need to diagnose MCP server connection
Malfunction after resuming session	Need to check session status
Works in other projects	Possible project-specific configuration issue

Preventive Advice

To prevent issues, we recommend the following:

Regularly run
npm run build
: Detect issues early
Frequent commits: Easy to revert if issues occur
Update Plans.md: Enable tracking of change history

Notes

Automatic fixes are attempted up to 3 times
Escalate if 3 attempts fail
Always confirm before performing destructive operations
Record fix history in session-log.md

🔧 Utilizing LSP Features

For problem-solving, use LSP (Language Server Protocol) to accurately identify the cause.

Issue Detection via LSP Diagnostics

🔍 Running LSP diagnostics...

📊 Diagnosis results:

| File | Line | Message |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' may be undefined |
| src/components/Form.tsx | 45 | Type 'string' cannot be assigned to type 'number' |

→ 2 issues detected
→ The above are highly likely to be the cause of "it doesn't work"

Cause Tracking via Go-to-definition

🔍 Tracking cause

Error: Cannot read property 'name' of undefined

Tracking:
1. src/pages/user.tsx:34 - Referencing user.name
2. src/hooks/useUser.ts:12 - Returns user ← Go-to-definition
3. src/api/user.ts:8 - API response may be null

→ Cause is insufficient handling of API errors

Usage Guide for VibeCoder

Symptom	LSP Utilization
"It doesn't work"	Identify error locations with Diagnostics
"What's wrong?"	Track causes with Go-to-definition
"When did it break?"	Check change impacts with Find-references

Details: docs/LSP_INTEGRATION.md

troubleshoot

NPX Install

Tags

SKILL.md Content (Chinese)

Troubleshoot Skill

Trigger Phrases

Overview

Diagnosis Flow

Step 1: Confirm Symptoms

Step 2: Automatic Diagnosis

Step 3: Identify Problem Category

Issue-Specific Solutions

"Buttons won't work / Forms won't submit / UI is broken"

"Screen is completely white"

"npm install failed"

"Git is behaving strangely"

Response Patterns for VibeCoder

Pattern 1: Automatically Fixable

Pattern 2: Confirmation Required

Pattern 3: Escalation

Automatic Responses to Common Questions

Diagnosis Commands

Quick Diagnosis

Detailed Diagnosis

Claude Code-Specific Diagnosis (CC 2.1.49+)

Authentication Diagnosis (CC 2.1.41+)

For VibeCoder

Troubleshooting Collaboration Flow

Cases Where
`/debug`
Is Particularly Effective

Preventive Advice

Notes

🔧 Utilizing LSP Features

Issue Detection via LSP Diagnostics

Cause Tracking via Go-to-definition

Usage Guide for VibeCoder