turbo-doctor

パイプライン診断

対象範囲

• 既存のパイプラインの問題を対話形式で診断し、修正します。
• 新しいパイプラインは構築しません。新規構築は /turbo-builder の担当です。
• コマンドリファレンスとしては使用しません。CLI の構文やエラーパターンの検索だけが必要な場合は、代わりに /turbo-operations スキルを使用してください。

体系的な診断ワークフローに従って、パイプラインの問題を特定し、解決します。

モードの判定

コマンドを実行する前に、Bash ツールを利用できるか確認します。

• Bash を利用できる場合（CLI モード）：コマンドを直接実行し、出力を解析します。
• Bash を利用できない場合（リファレンスモード）：ユーザーが実行するコマンドを提示します。出力を貼り付けてもらい、それを分析して推奨事項を提示します。

診断ワークフロー

以下の手順を順番に実行します。各手順は前の手順を踏まえているため、省略しないでください。

ステップ 1：認証の確認

ログイン状態を確認するため、goldsky project list 2>&1 を実行します。

• ログイン済みの場合： 現在のプロジェクトを確認し、続行します。
• 未ログインの場合： 認証が必要であることをユーザーに伝えます。手順については /auth-setup スキルを使用してください。認証が確認できるまで続行しないでください。

ステップ 2：パイプラインの特定

すべてのパイプラインを表示するため、goldsky turbo list を実行します。

診断するパイプラインをユーザーに尋ねます。すでに指定されている場合は、一覧に存在することを確認します。

パイプラインの現在のステータス（running、paused、error、completed、starting）を確認します。

ステップ 3：パイプラインのステータスを分析

ステータスに応じて、次のように対応します。

• running — パイプラインは稼働中です。問題がデータ品質、レイテンシ、または予期しない動作に関するものかを確認します。ステップ 4 に進みます。
• error — パイプラインでエラーが発生しています。これは最もよくあるケースです。ログ分析のため、ステップ 4 に進みます。
• paused — パイプラインは手動で一時停止されています。再開するかどうかを尋ねます。
• starting — パイプラインは初期化中です。起動状態がどのくらい続いているかを尋ねます。10 分を超えている場合は、ログを確認します。
• completed — ジョブモードのパイプラインが完了しています。想定していた動作と実際の動作を尋ねます。

ステップ 4：ログの確認

最近のログを取得するため、goldsky turbo logs <pipeline-name> --tail 100 2>&1 を実行します。

既知のエラーパターンに照らして出力を分析します。次の項目を含む、/turbo-operations スキルのエラーパターンを参照してください。

• 接続エラー — シンクに到達できない、認証に失敗する、タイムアウト
• スキーマエラー — カラムの不一致、型の不一致、カラムの欠落
• リソースエラー — OOM、ディスク容量不足、レート制限
• データエラー — デシリアライズの失敗、無効なブロック範囲
• 設定エラー — 無効な YAML、未知のデータセット、不正な変換

ステップ 5：シークレットの確認（該当する場合）

ログに接続エラーまたは認証エラーがある場合：

必要なシークレットがすべて存在することを確認するため、goldsky secret list を実行します。

利用可能であれば、パイプラインの YAML と照合します。シークレットの作成や更新の手順については、/secrets スキルを使用してください。

ステップ 6：診断結果の提示

次の形式で調査結果を提示します。

## Diagnosis

**Pipeline:** [name]
**Status:** [status]
**Issue:** [one-line summary]

**Root cause:**
[Detailed explanation of what's wrong]

**Evidence:**
- [Log line or observation 1]
- [Log line or observation 2]

**Recommended fix:**
1. [Step 1]
2. [Step 2]

**Prevention:**
[How to avoid this in the future]

ステップ 7：修正の提案

修正に CLI コマンド（再起動、シークレットの更新、再デプロイ）が含まれる場合は、実行を申し出ます。変更を行う前には、必ずユーザーに確認してください。

よくある修正方法：

• 再起動： goldsky turbo restart <name>（最初から開始する場合は --clear-state）
• シークレットの更新： goldsky secret update <name> --value "$(cat /secure/path/secret.json)" を使用して、既存のシークレットをその場でローテーションします。JSON 形式と認証情報の取り扱いについては、認証情報のローテーションを参照してください。使用中のシークレットを削除して再作成しないでください。create とは異なり、update は値の入力を求めません。認証情報を会話に出力しないでください。
• 再デプロイ： goldsky turbo delete <name> の後に goldsky turbo apply <file.yaml> を実行します。
• 再開： goldsky turbo resume <name>（一時停止中のパイプラインの場合）

重要なルール

• 問題を推測してはいけません。必ず最初にログとステータスを確認してください。
• 確信がない場合は、その旨を伝え、役立つ追加情報を提案してください。
• ジョブモードのパイプラインは一時停止、再開、再起動できず、削除して再デプロイすることしかできない点に注意してください。
• 破壊的なコマンド（delete、restart --clear-state）を実行する前に、必ず確認してください。
• CLI で診断できない問題の場合は、具体的なエラーメッセージを添えて Goldsky サポートに問い合わせるよう提案してください。

関連項目

• /turbo-operations — CLI コマンド、ライフサイクル操作、エラーパターンのリファレンス
• /turbo-builder — パイプラインの新規ビルドとデプロイ
• /turbo-pipelines — YAML 設定とアーキテクチャのリファレンス
• /secrets — シンクの認証情報を管理