authoring-signals-scouts

Scout の作成

Scout とは、設定された間隔で自動的に起動し、PostHog の 1 つのプロジェクトを調べて、本当に提示する価値がある情報を判断し、それを Signals の受信トレイに finding として出力するエージェントです。あるいは、何もない状態で終了することもあり、これも正当な結果です。PostHog には、canonical scout の一群（複数のプロダクトを横断する汎用 Scout と、サーフェスごとの専門 Scout）が用意されています。このスキルを使うと、特定のプロジェクトに合わせてこれらの canonical scout を調整したり、一群の Scout では対応できないユースケース向けに新しい Scout を一から作成したりできます。

Scout は、名前が signals-scout- で始まる LLMSkill にすぎません。ハーネスはプロジェクトのスキルから signals-scout-* をグロブ検索して Scout を見つけ、その本文をエージェントのシステムプロンプトとしてそのまま読み込み、同梱されている参照ファイルは必要に応じて段階的に読み込みます。signals-scout- という名前の接頭辞は必須です。これ以外の名前のスキルは Scout として実行されません。

作成に取りかかる前に

抽象的な状態で Scout を書き始めないでください。まず対象プロジェクトを把握してください。Scout の品質は、監視対象のデータとの適合度で決まります。

1. プロジェクトを読み取ります。 posthog:signals-scout-project-profile-get は、Scout 自身が初回起動時に参照する、決定論的なスナップショットを返します。使用中のプロダクト、リーチ／バーストの指標を伴う主要イベント、連携、既存の受信トレイ件数が含まれます。Scout が特定のイベントを監視する場合は、そのイベントが存在することを確認し、posthog:read-data-schema で構造を調べてください。プロジェクトで取得されていないイベントを対象にする Scout は、最初から機能しません。
2. すでに動作しているものを確認します。 posthog:signals-scout-config-list は、プロジェクト上にあるすべての Scout のスケジュール、enabled、emit の設定に加え、各 Scout の description（スキルのフロントマターから取得）を一覧表示します。本文を読み込まなくても、各 Scout の監視対象を把握できます。canonical scout がすでにカバーしているサーフェスを重複させず、既存の Scout を調整してください。
3. 最も近い canonical scout を読みます。 それがテンプレートであり、参照すべき形式です。posthog:llma-skill-get {"skill_name": "signals-scout-<x>"}（チームごとの行）で取得するか、リポジトリの products/signals/skills/signals-scout-*/ から読み取ってください。汎用 Scout（signals-scout-general）は幅広い用途のテンプレートです。対象範囲が特定の領域に限られる場合は、対象のサーフェスに最も近い専門 Scout を選んでください。現在のラインナップは posthog:llma-skill-list {"search": "signals-scout"} で確認できます（エラー追跡、ログ、AI の可観測性、実験、フィーチャーフラグ、セッションリプレイ、ウェブ分析、アンケートなど、ほとんどのプロダクトサーフェスに専門 Scout があります）。
4. 受信トレイに目を通します。 posthog:inbox-reports-list で実際に届いている finding を確認し、Scout がノイズではなく有益な情報を追加できるよう調整してください。

方針を選ぶ

判断すべきことは 2 つあります。何を作るか、そしてどこに置くかです。

何を作るか

状況	アプローチ
canonical scout は近いが、対象プロジェクトには範囲が広すぎる／ノイズが多すぎる／除外条件が足りない	調整します。対象範囲を絞り、除外条件を追加し、しきい値を調整してください。
canonical scout がカバーしていないサーフェス（カスタムイベント、プロダクト固有のファネルなど）が必要	新しい Scout を一から作成します。最も近い canonical scout をひな形としてコピーし、領域の識別条件と探索パターンを置き換えてください。
Scout の実行タイミングや実行するかどうかだけを変更したい	作成は不要です。設定を調整してください（「実行設定」を参照）。

追加場所

パス	方法	使用するケース
チームごと（一般的なユーザー向けの方法）	プロジェクトのスキルストアで signals-scout-* LLMSkill 行を作成／編集し、posthog:llma-skill-create / -update / -file-create を使用してから、posthog:signals-scout-config-create でその設定をすぐに登録します。	1 つのプロジェクト向けにカスタマイズする場合です。ハーネスは次のティックでその行を glob で取り込みます。正規同期では、編集した（「分岐した」）行はそのまま保持されます。
正規（PostHog のコントリビューター向け）	products/signals/skills/signals-scout-*/ 配下のディスク上のファイルを編集し、lint／ビルドを実行して PR を作成します。	参加しているすべてのプロジェクト向けにスカウトを改善する場合です。lazy_seed により、次のティックで参加しているすべてのチームに反映されます。

既存のものをその場で変更する場合の注意点： チーム用に正規スカウトの行を編集すると、行は 分岐した状態になり、そのスカウトに対する上流の改善を受け取れなくなります。必要なのが 動作の_追加_だけであれば、正規版はそのままにして、新しく名前の異なるスカウト （signals-scout-<your-scope>）を作成することをおすすめします。

スキルストアの正確な呼び出し方法、ビルド／lint コマンド、シードの仕組みについては、 references/lifecycle-and-testing.md を参照してください。

スカウトを書く

まずパターンを選びます。references/scout-patterns.mdには、スカウトが該当する参照アーキテクチャのレシピがまとめられています。異常監視、ウォッチリストの探索／活用、プロダクト横断の相関、レコメンデーション／ギャップ、データウェアハウスを基盤とするソース、カスタムの単一イベント、自由記述のテーマ、外部ツール／コードなど、それぞれに雛形としてコピーできる標準的なスカウトが対応付けられています。また、重要な点として、スカウトは分析イベントだけでなく、PostHog がデータウェアハウスに取り込むあらゆるソース（Slack チャンネルの同期、課金システム、CRM、サポート受信箱など）と、サンドボックスからアクセスできる外部システムを監視できます。最も近いパターンを見つけてから、本文を書きます。

references/scout-anatomy.mdに従ってください。フロントマターのスキーマ、標準的な本文構成（簡潔な締めくくり → 状況把握 → ドメイン識別子 → パターンの探索 → メモリーの保存 → 判断 → 除外条件 → 締めくくり）、本文を簡潔に保つルール、スペシャリストとジェネラリストそれぞれのコピー可能なスケルトンテンプレートが記載されています。

フリート全体の推論に使う、重要なクラフトに関する参照資料が2つあります。優れたスカウトの判断とメモリーのセクションはこれらを基盤とするため、該当セクションを書く前に読んでください。

• references/emit-contract.md — emit-signalが受け取る内容、信頼度の基準、深刻度、重複排除キー、finding_id、説明文の要件、具体的な例が記載されています。スカウトが_何を基準を満たすと判断するか_、また_検出結果をどう書くか_を定める資料です。
• references/dedupe-and-memory.md — 4状態の分類（新規／重要な更新／対応済み／対処済みまたはノイズ）、スクラッチパッドのキー接頭辞の用語、プロジェクト横断のノイズパターンが記載されています。スカウトが再通知を避け、実行を重ねるごとに学習する方法を定める資料です。

スカウトの設計で最も重要な判断は、シグナルとノイズを識別する基準です。これは、「調査する価値があるもの」と「ベースライン」を切り分ける、低コストなプロファイル形状の確認です。エラートラッキングではcountとdistinct_usersの比率が、CSPでは生の件数に対するリーチが基準になります。新しいスカウトにも固有の基準が必要です。各実行の基準となるよう、本文の上部付近に明記してください。

実行方法（設定）

スカウトのスケジュールと通知動作は、スキル本文とは別のSignalScoutConfigで管理されます。新しいスカウトの場合は、スキルの作成直後にposthog:signals-scout-config-create {"skill_name": "signals-scout-<scope>", ...}で設定を登録し、以下のフィールドを同じ呼び出しで設定してください。スカウトを一度も実行する前に、無効またはドライランの状態で作成することもできます。（これはアップサートです。コーディネーターによってすでに行が自動登録されている場合、指定したフィールドがその行に適用されます。）設定しない場合、次の実行タイミングでコーディネーターが有効な毎時のデフォルト設定を自動登録します（最大で約30分かかります）。既存のスカウトはposthog:signals-scout-config-updateで調整します（-config-listでidを確認してください）。

• run_interval_minutes — 10～43200。デフォルトは60（毎時）です。通知が多い、またはコストの高いスカウトは、値を大きくして実行頻度を下げます。
• enabled — falseにするとスカウトが完全に停止します（コーディネーターが実行をスキップします）。
• emit — デフォルトは**trueです。スカウトは検出結果を直接受信箱に書き込みます。標準的な流れは、スカウトを作成して通知させることです。実際に受信箱に届いた内容を見るのが、調整する最も速い方法です。特に慎重を期したい場合にのみemit=false（ドライラン）**にします。スカウトは引き続き実行され、推論内容もログに記録されますが、受信箱には何も書き込みません。通知が多い、コストが高い、またはリスクが大きいと予想されるスカウトではドライランを使います。ほとんどのスカウトでは、通知を有効にして受信箱を確認するほうが適切です。

テストループ

ユーザーとして同期実行を強制することはできません。スカウトはスケジュールに従って実行されます。標準のループは出力＋確認です。スカウトを稼働させ、出力させ、実際に届いた内容を基準に調整します。

1. スカウトを稼働させます（既定では emit=true）。すぐに実行されるよう run_interval_minutes を短く設定します。1 時間ごとの既定値がコーディネーターによって自動登録されるのを待つのではなく、llma-skill-create の直後に次のように posthog:signals-scout-config-create {"skill_name": ..., "run_interval_minutes": 10} を使って作成時に設定します。
2. 実行後、何が行われたかを確認します。posthog:inbox-reports-list（実際に出力された調査結果）、posthog:signals-scout-runs-list（実行の概要）、-runs-retrieve（特定の実行の詳細な推論）、-scratchpad-search（書き込まれた永続メモリー）を使います。
3. 本文を改善します。判別条件を厳密にし、誤検出した対象に対する除外条件を追加し、出力の調整を修正します。
4. 適切な調査結果が届くようになったら、実行間隔を持続可能な値（1 時間以上）に戻します。

慎重に進めたい場合は？ まず emit=false に設定してドライランします。-config-create で emit=false を指定して設定を作成すれば、スカウトが初回から実際に出力することはありません。実行され、出力されるはずだった内容が記録されます（-runs-list ／ -runs-retrieve で確認可能）。ただし、インボックスには書き込まれません。確認して改善した後、emit=true に切り替えます。頻繁に出力する、高コスト、または重要度の高いスカウトには有効です。それ以外の場合は、まず出力させてインボックスを確認するほうが、調整を進める近道です。

リポジトリのコントリビューターは、hogli sync:skill とハーネスのローカル実行パスを使って、より高速なループを利用できます。詳しくは references/lifecycle-and-testing.md を参照してください。

スカウトを変更するのではなく、何をしているかを確認する場合（全体の状況の調査、個々の実行の確認、スクラッチパッドのメモリーの確認、パフォーマンスの評価）は、読み取り専用のコンパニオンスキル exploring-signals-scouts を使います。スカウトの設定、実行、スクラッチパッドの各機能に変更があった場合は、2 つのスキルの内容を同期してください。

v1 スカウトの品質基準

• 冒頭近くに、名前を付けた低コストのシグナルとノイズの判別条件があること。
• 実行対象が平常状態または存在しない場合に、深掘りにコストをかけずに済む迅速な終了処理があること。
• 実際に実行するクエリやツールを含む、具体的な調査パターンが 2～4 個あること。厳格なチェックリストではなく、出発点として示します。
• このプロジェクトで既知のノイズ（単一ユーザー特有の挙動、開発環境での急増、許可リストに登録済みのエンティティ）を列挙した除外条件があること。
• 出力契約に合わせて調整された判定セクションがあること（信頼度が 0.65 以上なら出力し、それ未満ならメモリーに書き込みます）。
• スカウトが実行のたびに賢くなるよう、スクラッチパッドのプレフィックスを使ったメモリー保存のガイダンスがあること。
• 本文は簡潔にすること（詳細は references/ に移します）。すべての行が、実行のたびに繰り返し発生するトークンコストになります。