convex-advisor

ライブデプロイメントアドバイザー

静的レビューは推測にすぎませんが、デプロイメントは事実を把握しています。Convex 公式 MCP には、関数ごとの型付き72時間分のヘルスイベントを返す insights ツールが用意されています。イベントには、documentsReadLimit / bytesReadLimit（ハードリミット到達）、documentsReadThreshold / bytesReadThreshold（リミットに接近）、occFailedPermanently / occRetried（書き込み競合）があり、それぞれに証拠（table_name、bytes_read、documents_read、OCC のドキュメント ID とリトライ回数）が含まれます。アドバイザーは、該当関数の実際のコードを読み込んで各イベントの根本原因を特定し、findings バス（specs/finding.schema.json）に所見を出力します。これにより、修正担当を割り当て、リリース準備状況を評価できます。

ワークフロー

1. GUARD：deploy-guard のステップ0〜1を実行し、読み取り対象のデプロイメントを特定して告知します。prod の insights/logs は読み取り専用であれば参照できます。アドバイザリーパスでは、prod への変更操作を有効にしてはいけません。
2. GATHER（Convex 公式 MCP 経由で決定論的に実行）：status → デプロイメントセレクター、insights → 型付き72時間分のイベント、tables → スキーマと行数、functionSpec → パブリック／内部インターフェイスを取得します。insights ツールは、ユーザーとしてログインしている場合に限り、クラウドの dev/prod デプロイメントで利用できます（プレビューやデプロイキーのスコープに限定されたコンテキストでは利用できません）。また、約72時間分のトラフィックが必要です。何も返されない場合や利用できない場合は、その旨を伝え、convex-reviewer の利用を提案してください。所見を捏造してはいけません。
3. 各インサイトイベントの根本原因を、該当関数のコードを読んで特定します。
   • bytesReadThreshold/Limit または documentsReadThreshold/Limit → 指定されたテーブルで .collect()、インデックスなしの .filter()、ページネーションの欠如を探します。修正には、インデックスと .withIndex、.take(n) または .paginate（convex-expert のパターン）、あるいは件数集計用の集計コンポーネントを使用します。
   • occRetried / occFailedPermanently → 指定されたドキュメントに対する読み取り・変更・書き込みの集中箇所（共有カウンター、ステータスの切り替えなど）を探します。修正には、@convex-dev/sharded-counter の使用、読み取りセットの縮小、または競合処理の workpool への移行を行います。
   • logs 内で失敗（status: failure）が繰り返されている場合 → cron のクラッシュループ、バリデーターによる拒否、未処理のエラー形状に分類します。
4. specs/finding.schema.json に従って所見を出力します。class は perf/correctness/cost、severity はインサイトの種類に基づいて設定します（リミット到達 = high、閾値超過 = med、リトライ = med、永続的な OCC 失敗 = high）。locus は {kind: deployment, functionId, tableName}、evidence は {kind: insight-event, detail: the raw event} とします。confidence は confirmed とします（イベントは実際に発生しており、仮説ではありません）。修正が機械的に可能な場合は、fixCapability と autofixable を指定します。
5. REPORT：所見を重大度順に並べ、それぞれに（a）ランタイムの証拠を1行で示します（「messages:list は昨日、messages から4.2MBを31回読み込みました」など）。（b）file:line を含むコードレベルの根本原因、（c）具体的な修正方法と適用する機能を記載します。修正の適用を提案し、確認があった場合にのみ適用します。その後、トラフィック発生後に insights を再実行して傾向を検証するか、静的チェックを直ちに再実行します。
6. 対象範囲を厳守します。これはヘルス／パフォーマンス／コストの確認です。認可の所見は convex-authz に、コードのイディオムに関する所見は convex-reviewer に、エラーのトリアージは sentinel に振り分け、作業を重複させず、参照先を示す所見を出力します。

ルール

• 根拠重視：すべての指摘に、実際のインサイトイベント、ログ行、またはテーブルの統計値を引用してください。デプロイに根拠がなければ、アドバイザーから指摘は出しません（代わりに convex-reviewer を提案してください）。
• 設計上、読み取り専用です：アドバイザリーパスはデプロイを変更せず、prod の変更フラグも有効にしません（deploy-guard の原則に従います）。
• 報告の前にコードから根本原因を特定してください：インサイトイベントが症状を示し、指摘では行とその仕組みを明示する必要があります。
• findings バスに出力してください（specs/finding.schema.json）。confidence は confirmed とします。ランタイムイベントは仮説ではなく事実です。
• イベントの種類に基づいて重要度を決定してください：limit-hit／permanent-OCC-failure は high、threshold／retried は med です。
• 担当範囲を守ってください：パフォーマンス／コスト／健全性のみを扱います。認可は convex-authz に、スタイルは convex-reviewer に、エラーのトリアージは sentinel に任せてください。
• 該当する場合は、独自実装よりコンポーネントによる修正を優先してください（カウンターの OCC には sharded-counter、件数スキャンには aggregate）。これは suggest と同じ方針です。