caveman-discover

Caveman Cloud 向けに、このリポジトリの LLM ワークフローにラベルを付けます。 ワークフローとは、コードが実行するジョブのことです。「サポートチケットに回答する」「夜間ダイジェストを作成する」「評価スイートを実行する」などであり、技術のことではありません。すべてのゲートウェイリクエストにはワークフローラベルを付けられます。ラベルのないトラフィックはすべて、1 つの unlabeled-workflow バケットに入ります。ワークフローを見つけ、適切な名前を付け、ラベルを設定し、問題が起きていないことを確認するのがあなたの役目です。

コードを変更するため、ユーザーの通常のレビュー手順に従います。**まずテーブルを提案し、ユーザーの同意を得てから適用してください。**すでにラベルが付いているリポジトリで再実行しても、変更は発生しないようにします（冪等性）。

このスキルはオペレーターが呼び出します。unlabeled-traffic の Cave Plan 観測はレビュー専用であり、アドバイザリーファイル、提案、Draft PR は作成しません。テレメトリによって呼び出し箇所が選択された、または編集が許可されたと推測しないでください。リポジトリを独自に調査し、ラベル付けテーブルを提示して、コードを変更する前にユーザーの承認を待ってください。

ステップ 1 — ワークフローを調査する

インポート元からではなく、リポジトリのエントリーポイントからたどります。

• LLM を（直接、または複数の層を介して）呼び出す HTTP/RPC ハンドラー
• スケジュールされたジョブ：LLM コードを呼び出す cron 定義、キューコンシューマー、ワーカー、GitHub Actions
• CLI コマンドとスクリプト（scripts/、bin/、package.json のスクリプト）
• 実際のトークンを消費する評価／テストハーネス
• フレームワーク内の個別のエージェントやチェーン（通常、各 LangGraph グラフ、各クルー、各エージェント定義がそれぞれ独自のワークフローです）

1 つのワークフローは、人が 1 つのジョブとして名付けるものです。同じリクエストハンドラー内に呼び出し箇所が 10 個あっても、ワークフローは 1 つです。3 つのジョブで共有される llm.ts ヘルパーがあっても、ワークフローは 3 つです（ラベルは呼び出し元に設定し、共有ヘルパーには設定しません）。

ステップ 2 — 名前を付ける

スラッグの文法（ゲートウェイで強制されます）：小文字の [a-z0-9_-]、1～96 文字。技術ではなく、ジョブに名前を付けます。

• 適切な例：support-reply、nightly-digest、pr-review、eval-suite、onboarding-email
• 不適切な例：openai-calls（技術名）、main（内容がわかりません）、SupportReply（無効）、johns-test-3（長期的に使えません）

名前はほぼ永久に使われます。後で名前を変更すると、利用額の履歴が分割されます。コードからジョブの目的が明確でない場合は、ファイル名からスラッグを導出し、目的を推測して創作するのではなく、テーブル内で review と記載してください。

ステップ 3 — 提案してから適用する

次のテーブルを提示し、適用してよいか尋ねます。

| workflow | job | where | how it gets labeled |
|---|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 | defaultHeaders on the reply client |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 | header on the digest client |
| eval-suite (review) | scripts/eval.ts:8 — purpose inferred from filename | scripts/eval.ts:8 | env override at invocation |

次に、各呼び出し箇所で利用できる最も簡単な方法を使って、各ラベルを設定します。

• @caveman-ai/sdk / caveman_cloud SDK：トレースごとの workflow オプション、または単一ジョブのサービスが構築するクライアントに設定する defaultWorkflow。
• 生のプロバイダー SDK（OpenAI/Anthropic/LangChain/LiteLLM/Vercel）：x-cave-api-key がすでに設定されている defaultHeaders／default_headers／extra_headers ブロックに、"x-cave-workflow": "<slug>" を追加します。複数のジョブで共有するクライアントの場合は、呼び出しごとにヘッダーを渡すか（上記のすべての SDK がリクエスト単位のヘッダー上書きを受け付けます）、各ジョブ専用の軽量なクライアントを用意します。
• ラップされたコーディングエージェント（caveman wrap）：呼び出し箇所（cron 行、CI ステップ）に --workflow <slug> フラグ、または CAVE_WORKFLOW=<slug> 環境変数を設定します。
• 生の HTTP：リクエストに x-cave-workflow ヘッダーを追加します。

呼び出し元にラベルを設定し、差分を最小限に抑え、リポジトリのスタイルに合わせてください。呼び出し箇所が Caveman ゲートウェイを経由していない場合はラベルを設定せず、レポートの「未設定」に記載してください（ラベルはゲートウェイを通るトラフィックにのみ付与されます。設定は caveman-setup スキルの役割です）。

ステップ 4 — 検証する

リポジトリですでに使われている方法（テスト、開発用スクリプト、curl 1 回など）で、ラベルを付けた経路を 1 つ実行します。そのうえで、リクエストが引き続き成功することを確認してください（無効なラベルの場合、ゲートウェイは 400 cave_invalid_request_header を返します。その場合はスラッグを修正してください）。ラベル付きの利用額は、各ワークフローが次に実行されると、ダッシュボードの /activity?tab=workflows に表示されます。スケジュール実行のジョブはスケジュールが発動したときに表示されるため、すでに稼働中であるかのように装うのではなく、そのことをレポートに記載してください。

ステップ 5 — レポート

## Workflows labeled

| workflow | job | where |
|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 |

Verified: <the labeled path you actually exercised, and what you observed>
Lands at: <DASHBOARD>/activity?tab=workflows — each row appears as that workflow
next runs. Anything still unlabeled shows as `unlabeled-workflow`.
Not wired (no gateway routing, so no label): <list or "none">
Marked review: <slugs whose purpose was inferred from filenames, or "none">

LLM のエントリーポイントがまったく見つからなかった場合は、そのことをそのまま伝え、表を作り上げるのではなく、セットアップスキル（<docs origin>/docs/agent-setup.md）を案内してください。