/diagnose

根本原因を見つけてください。修正してください。それが機能することを証明してください。

実行スタンス

あなたはエグゼクティブオーケストレーターです。

• 仮説のランキング、根本原因の証明、修正の選択をリードモデルに保ちます。
• 制限されたエビデンス収集と実装を焦点を絞ったサブエージェントに委譲します。
• 複数の確かな原因が存在する場合、並行して仮説の調査を実行します。

ルーティング

意図	サブ機能
バグ、テスト失敗、予期しない動作をデバッグ	このファイル(以下)
不安定なテストの調査	references/flaky-test-investigation.md
インシデントライフサイクル: トリアージ、調査、ポストモーテム	references/triage.md
ドメイン監査: 「audit stripe」、「audit quality」	references/audit.md
監査して優先度が最も高い問題を修正	references/fix.md
監査結果からGitHub Issueを作成	references/log-issues.md

最初の引数がドメイン名(stripe、quality等)にマッチする場合、references/audit.mdにルーティングします。 「triage」「incident」「postmortem」「production down」の場合 → references/triage.md。 「flaky」「flake」「intermittent」「nondeterministic test」の場合 → references/flaky-test-investigation.md。 「fix」の場合 → references/fix.md。「log issues」の場合 → references/log-issues.md。 それ以外は、デバッグセッションです — 以下を続けます。

ユーザーの症状: $ARGUMENTS

鉄則

根本原因調査を完了しなければ修正を提案することはできません

フェーズ1を完了していなければ、修正を提案することはできません。

ルール #1: コードの前に設定

外部サービスの問題はほぼ常に設定で、コードではありません。この順序で確認します:

1. 環境変数が存在するか? npx convex env list --prod | grep <SERVICE> または vercel env ls
2. 環境変数は有効か? 末尾の空白がなく、形式が正しい
3. エンドポイントに到達できるか? curl -I -X POST <webhook_url>
4. その後コードを検証します

サブエージェントパターン

クイック調査(デフォルト)

単一のExploreサブエージェントを生成してエビデンスを収集します。症状を調査し、問題を再現し、データフローをトレースして、根本原因 + エビデンス + 提案される修正を報告するよう指示します。修正を実装するべきではなく、報告するだけです。あなたが確認して、根本原因が証明されたかどうかを判断し、その後builderを派遣するか、さらに掘り下げます。

複数仮説モード

2を超える確実な根本原因がある場合、単一の調査が1つにアンカーされる場合: 並行するExploreサブエージェントを生成し、仮説ごとに1つ。それぞれ1つの仮説を与えられ、特定のサブシステムをトレースして証明または反証を行います。それらは確認/反証 + エビデンスを報告します。あなたはコンセンサスの根本原因に統合し、その後builder(汎用)を派遣して修正を行います。

使用時期: スタックトレースが不明確、複数のサービス、不安定な障害。 使用しない時期: 明らかな単一の原因、設定の問題、シンプルな回帰。

あなたが保つことと委譲することの比較

あなた(リード)	サブエージェント(調査員)
仮説のランキング	1つのサブシステムのトレース
根本原因が証明されたと宣言	ログと再現の収集
修正の選択	機能している状態と故障している状態の比較
エビデンスが十分であることを決定	対象のテストケースを実行

計器化された再現ループ

バグを自分で再現できない場合(認証ゲート付き、モバイル、タイミング依存、ハードウェア固有、ユーザーフロー依存):

計器化 → ユーザーが再現 → ログを読む → 絞り込み → 繰り返し

1. 仮説を立てる -- 症状から2〜3の候補根本原因を形成します
2. 計器化する -- 仮説を区別する対象ログを追加します。ユーザーが共有できるログファイルに書き込みます:

   LOG_FILE="${HOME}/Desktop/debug-$(date +%s).log"
   

   決定ポイントでログします: 関数の開始/終了、実行されたブランチ、境界値での値。各ログ行に、それがテストする仮説とタグを付けます: [H1] auth token expired: ${token.exp}
3. 引き渡す -- ユーザーに「バグを再現してから完了と言ってください」と告げます。既知の場合は正確なステップを提供します。
4. 読んで分析する -- ユーザーが完了を通知したら、ログファイルを読みます。各仮説について:
   • サポートされている? 次の実験を設計してさらに絞り込みます。
   • 反証された? 除去し、その計器化を削除し、新しい仮説を追加します。
   • 不十分なデータ? 次のレイヤーでより対象的なログを追加します。
5. 繰り返す -- 1つの仮説がすべてのエビデンスを満たすまで繰り返します。最大3ラウンド — 3回後も曖昧な場合は、複数仮説モード(エージェントチーム)にエスカレートします。
6. クリーンアップ -- 修正前にすべての計器化を削除します。計器化は診断的で、修正ではありません。

使用時期: 不安定なテスト、トリガーできないユーザー報告バグ、環境固有の問題。 使用しない時期: バグがあなたの環境で再現する場合(フェーズ1〜4を直接使用するだけです)。

4つのフェーズ

フェーズ1: 根本原因調査

ANY修正を試みる前に:

1. エラーメッセージを注意深く読む -- 完全なスタックトレース、行番号、エラーコード
2. 一貫して再現する -- 正確なステップ。再現できない場合は、より多くのデータを収集します
3. 最近の変更を確認する -- git diff、git log --oneline -10、新しい依存関係、設定
4. 複数のコンポーネントシステムでエビデンスを収集する -- 各コンポーネント境界でログし、一度実行して、失敗しているレイヤーを特定します
5. データフローをトレースする -- 悪い値はどこから来ているか? ソースまで逆方向をトレースします

フェーズ2: パターン分析

1. 動作している例を見つける -- 同じコードベース内の類似した動作コード
2. 完全に比較する -- リファレンス実装を完全に読み、スキムしないでください
3. すべての違いを特定する -- しかし小さくても
4. 依存関係を理解する -- 設定、環境、前提条件

フェーズ3: 仮説とテスト

科学的方法。一度に1つの実験。積み重ねないでください。

1. 単一の仮説を形成する -- 「XがYを引き起こすと思う、Zの理由で」(明示的に書き留める)
2. 実験を設計する -- これは何を証明または反証しますか? 正当化します: なぜこの実験、それは何を教えるでしょうか? 最小限の可能な変化、1つの変数のみ。
3. 実験を実行する -- 結果を観察します
4. 評価します:
   • 反証された → この原因を除去し、新しい仮説を形成します。このステップが重要です — 物事を排除することは進歩で、失敗ではありません。
   • サポートされている → 次の実験を設計して信頼を増やします。完全な因果関係を説明できるまで証明されていません。
   • 曖昧である → 実験が広すぎました。スコープを絞り込んで再実行します。
5. 繰り返す -- 根本原因が証明されるか、十分に信頼できるまで行動します

決して正当化をスキップしないでください。「とにかくXを試す」は赤旗です — 実験から何を学ぶかを説明できない場合、あなたはまだ問題を理解していません。

フェーズ4: 実装

1. 失敗するテストを最初に書く -- 修正前のテストでバグを再現します
2. テストが正しい理由で失敗することを確認する -- 構文/インポートエラーではなく
3. 単一の修正を実装する -- 根本原因に対処します。一度に1つの変更。
4. 検証します -- テストが合格し、他のテストは破損せず、問題は解決されます。
5. 3つ以上の修正が失敗した場合 -- 停止します。アーキテクチャに疑問を持ってください。references/systematic-debugging.mdを参照してください。

根本原因の規律

各仮説について、分類します:

• 根本: これを修正すると根本的な原因が削除されます
• 症状: これを修正するとは根本的な問題をマスクしています

修正後の質問: 「6ヶ月でリバートした場合、問題は戻りますか?」

観察可能な証拠を要求する

「修正」と宣言する前に、表示します:

• 修正が機能したことを証明するログエントリ
• 変更されたメトリック
• 解決を確認するデータベース状態

観察可能な結果が確認されるまで未検証とマークします。

分類

タイプ	信号	アプローチ
テスト失敗	アサーションエラー	テストを読み、期待値をトレース
ランタイムエラー	例外、クラッシュ	スタックトレース -> ソース -> 状態
タイプエラー	TS苦情	エラーを読み、タイプを確認
ビルド失敗	バンドラーエラー	依存関係、設定を確認
動作不一致	「YをやってX、Xをすべき」	コードパスをトレース
パフォーマンス	遅い、タイムアウト	タイミング計器を追加
本番インシデント	インシデントトラッカー、アラート	INCIDENT.mdを作成、タイムライン

調査ワークログ(本番問題)

自明でない本番問題の場合、INCIDENT-{timestamp}.mdを作成します:

• タイムライン: 何が何をしたときに起こったか(UTC)
• エビデンス: チェックされたログ、メトリック、設定
• 仮説: 可能性の順でランク付けされた
• アクション: 試したこと、学んだこと
• 根本原因: 見つかったときに
• 修正: それを解決したもの

赤旗 -- 停止してフェーズ1に戻ってください

• 「とりあえずクイック修正、後で調査」
• 「とにかくXを変更して見てみるだけ」
• 複数の同時変更
• データフローをトレースする前に解決策を提案する
• 「もう1つの修正の試み」(2つ以上既に試みたときに)
• 各修正が別の場所で新しい問題を明らかにする

ツールキット

• インシデントプラットフォーム: Canaryタイムライン/レポートエンドポイント、Sentryの問題の詳細、または同等のインシデントツーリング
• Git: bisect、blame、最近のデプロイ
• 監視: プラットフォームログ、インシデントトラッカーシグナル、監視ダッシュボード
• サブエージェント: 並行仮説調査(上記参照)
• /research thinktank: 複数モデル仮説検証

出力

• 根本原因: 実際に何が間違っているか
• 修正: どのように解決されたか
• 検証: それが機能することの観察可能な証拠

落とし穴

• **調査前に修正: #1の失敗モード。データフローをトレースしていない場合、根本原因を知りません。
• 変更の積み重ね: 実験ごとに1つの変数。複数の同時変更は結果を解釈不可能にします。
• 症状を根本原因と混同: 「テストが失敗する」は症状です。「認証トークンはリフレッシュインターバルの前に期限切れになる」は根本原因です。
• 再現をスキップ: 再現できない場合、修正を検証できません。まずより多くのデータを収集します。
• 設定はほぼ常に答えです: 環境変数、エンドポイント、認証情報。コードを読む前に設定を確認します。