[Skill 名] troubleshooting-guide

トラブルシューティングガイド

目次

• 概要
• 使用場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

ユーザーとサポートチームが一般的な問題を迅速に診断し、解決するのに役立つ、構造化されたトラブルシューティングドキュメントを作成します。

使用場面

• FAQドキュメント
• 一般的なエラーメッセージ
• デバッグガイド
• 既知の問題リスト
• エラーコードリファレンス
• パフォーマンスのトラブルシューティング
• 設定の問題
• インストールに関する問題

クイックスタート

• インストールに関する問題

# Troubleshooting Guide

## Quick Diagnosis

### Is the Service Working?

Check our [Status Page](https://status.example.com) first.

### Quick Health Checks

```bash
# 1. Check service is running
curl https://api.example.com/health

# 2. Check your API key
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/api/v1/status

# 3. Check network connectivity
ping api.example.com

# 4. Check DNS resolution
nslookup api.example.com
```

## Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents |
|---|---|
| [Issue: "Authentication Failed"](references/issue-authentication-failed.md) | Issue: "Authentication Failed" |
| [Issue: "Rate Limit Exceeded"](references/issue-rate-limit-exceeded.md) | Issue: "Rate Limit Exceeded" |
| [Issue: "Connection Timeout"](references/issue-connection-timeout.md) | Issue: "Connection Timeout" |
| [Issue: "Invalid JSON Response"](references/issue-invalid-json-response.md) | Issue: "Invalid JSON Response" |
| [Issue: "Slow Performance"](references/issue-slow-performance.md) | Issue: "Slow Performance" |

## Best Practices

### ✅ DO

- Start with most common issues
- Include error messages verbatim
- Provide step-by-step diagnostics
- Show expected vs actual output
- Include code examples
- Document error codes
- Add screenshots/videos
- Link to related documentation
- Keep solutions up-to-date
- Include workarounds
- Test all solutions

### ❌ DON'T

- Use vague descriptions
- Skip diagnostic steps
- Forget to show examples
- Assume technical knowledge
- Skip verification steps
- Forget edge cases

リファレンスガイド

references/ディレクトリにある詳細な実装です。

ベストプラクティス

✅ 実施すべきこと

• 最も一般的な問題から始める
• エラーメッセージをそのまま含める
• 段階的な診断を提供する
• 期待される出力と実際の出力を示す
• コード例を含める
• エラーコードを文書化する
• スクリーンショット/動画を追加する
• 関連ドキュメントへのリンクを貼る
• ソリューションを最新の状態に保つ
• 回避策を含める
• すべてのソリューションをテストする

❌ 実施すべきでないこと

• 曖昧な説明を使用する
• 診断手順を省略する
• 例を示すのを忘れる
• 技術的な知識を前提とする
• 検証手順を省略する
• エッジケースを忘れる