Rédaction de scouts Signals

Un scout est un agent planifié qui s'active à intervalle régulier, examine un projet PostHog, décide ce qui vaut vraiment la peine d'être signalé, et l'émet comme finding dans la boîte de réception Signals — ou ferme sans rien, ce qui est un vrai résultat. PostHog fournit une flotte de scouts canoniques (un généraliste multi-produits plus des spécialistes par surface). Cette compétence vous aide, vous et votre agent, à adapter ces scouts canoniques à un projet spécifique, ou à créer des scouts à partir de zéro pour un cas d'usage que la flotte ne couvre pas.

Un scout est simplement un LLMSkill dont le nom commence par signals-scout-. Le harness découvre les scouts en globbant signals-scout-* sur les compétences du projet, charge le corps tel quel comme prompt système de l'agent, et lit progressivement les fichiers de référence liés à la demande. Le préfixe de nom signals-scout- est structurel : une compétence nommée autrement ne s'exécutera jamais comme un scout.

Le travail avant l'écriture

Ne rédigez pas un scout dans l'abstrait. Ancrez-le d'abord dans le projet cible — un scout n'est bon que s'il convient aux données qu'il surveille.

1. Lisez le projet. posthog:signals-scout-project-profile-get retourne l'instantané déterministe dont le scout lui-même démarre à froid : produits en usage, événements principaux avec métriques de portée/burst, intégrations, compteurs de boîte de réception existants. Si le scout surveille un événement spécifique, confirmez son existence et vérifiez sa structure avec posthog:read-data-schema. Un scout pour un événement que le projet ne capture pas est mort-né.
2. Voyez ce qui tourne déjà. posthog:signals-scout-config-list liste chaque scout existant sur le projet avec son calendrier, son statut enabled et sa posture emit, plus la description de chaque scout (tirée du frontmatter de la compétence) pour que vous sachiez ce qu'un scout surveille sans charger son corps. Ne dupliquez pas une surface qu'un scout canonique couvre déjà — adaptez-le plutôt.
3. Lisez le scout canonique le plus proche. C'est votre modèle et votre forme de référence. Récupérez-le avec posthog:llma-skill-get {"skill_name": "signals-scout-<x>"} (lignes par équipe) ou lisez-le depuis le repo à products/signals/skills/signals-scout-*/. Le généraliste (signals-scout-general) est le large modèle ; si votre champ est serré au domaine, choisissez le spécialiste le plus proche de votre surface — listez la flotte active avec posthog:llma-skill-list {"search": "signals-scout"} (des spécialistes existent pour la plupart des surfaces produits : error tracking, logs, observabilité IA, expériences, feature flags, session replay, web analytics, surveys, et plus).
4. Parcourez la boîte de réception. posthog:inbox-reports-list montre quels findings arrivent réellement — calibrez pour que votre scout ajoute du signal, pas du bruit.

Choisir le chemin

Il y a deux décisions indépendantes : ce que vous construisez, et où il vit.

Quoi

Où

Compromis d'adaptation sur place : modifier la ligne canonique d'un scout pour votre équipe la marque divergée — vous cessez de recevoir les améliorations amont pour ce scout. Si vous avez besoin d'un comportement supplémentaire seulement, préférez créer un nouveau scout avec un nom différent (signals-scout-<votre-portée>) et laisser le canonique intact.

Voir references/lifecycle-and-testing.md pour les appels exacts du magasin de compétences, les commandes build/lint, et comment fonctionne le seeding.

Rédiger le scout

Commencez par choisir la forme. references/scout-patterns.md est un recueil des architectures de référence dans lesquelles les scouts se divisent — anomaly watcher, watchlist explore/exploit, cross-product correlation, recommendation/gap, warehouse-backed source, custom single-event, open-text theme, external-tool/code — chacune mappée à un scout canonique que vous pouvez copier comme scaffolding. Cela souligne aussi le point clé qu'un scout peut surveiller n'importe quelle source que PostHog ingère dans l'entrepôt de données, pas juste les événements analytics (une sync Slack channel, un système de facturation, un CRM, une boîte de réception support), plus les systèmes externes accessibles depuis le sandbox. Trouvez le pattern le plus proche, puis rédigez le corps.

Suivez references/scout-anatomy.md — elle contient le schéma frontmatter, la structure canonique du corps (quick close-out → orient → domain discriminator → explore patterns → save-memory → decide → disqualifiers → close-out), la règle lean-body, et des templates skeleton prêts à copier pour un spécialiste et le généraliste.

Deux références craft que toute la flotte raisonne en termes de — les sections Decide et memory d'un bon scout sont construites dessus, lisez-les avant d'écrire ces sections :

• references/emit-contract.md — ce que emit-signal prend, la rubrique de confiance, severity, dedupe keys, finding_id, le contrat prose de description, et un exemple travaillé. C'est comment votre scout décide ce qui passe le bar et comment rédiger le finding.
• references/dedupe-and-memory.md — le classifieur quatre états (net-new / material-update / already-covered / addressed-or-noise), le vocabulaire de préfixe de clé scratchpad, et les patterns de bruit inter-projets. C'est comment votre scout évite de ré-émettre et apprend à travers les runs.

La décision de conception la plus importante dans tout scout est son discriminant signal-vs-noise — la lecture bon marché de forme profile qui sépare "vaut la peine d'investiguer" de "baseline". Pour error tracking c'est le ratio count vs distinct_users ; pour CSP c'est la portée sur le compte brut. Votre nouveau scout a besoin du sien. Nommez-le explicitement près du haut du corps pour que chaque run s'ancre dessus.

Posture d'exécution (config)

Le calendrier et le comportement emit d'un scout vivent sur son SignalScoutConfig, séparé du corps de la compétence. Pour un scout tout neuf, enregistrez le config immédiatement après avoir créé la compétence avec posthog:signals-scout-config-create {"skill_name": "signals-scout-<portée>", ...}, en définissant n'importe lequel des champs ci-dessous dans le même appel — y compris le créer désactivé ou en dry-run avant qu'il s'exécute. (C'est un upsert : si le coordinateur a déjà auto-enregistré la ligne, vos champs sont appliqués.) Sinon le coordinateur auto-enregistre un défaut horaire activé au prochain tick (~30 min). Pour un scout existant, accordez avec posthog:signals-scout-config-update (trouvez l'id via -config-list) :

• run_interval_minutes — 10 à 43200. Défaut 60 (horaire). Ralentissez un scout bavard ou coûteux en augmentant cela.
• enabled — false met le scout en pause entièrement (coordinateur le saute).
• emit — défaut true : le scout écrit ses findings directement dans la boîte de réception. Le flux standard est de faire un scout et le laisser émettre — voir ce qui arrive réellement est le moyen le plus rapide de le calibrer. Définissez emit=false (dry-run) seulement quand vous voulez être extra prudent : le scout s'exécute toujours et enregistre son raisonnement mais n'écrit rien dans la boîte de réception. Recourez au dry-run sur un scout que vous vous attendez à être bavard, coûteux, ou haute-stakes ; pour la plupart des scouts, juste émettre et regarder la boîte de réception est la meilleure boucle.

Boucle de test

Vous ne pouvez pas forcer un run synchrone en tant qu'utilisateur — les scouts s'activent selon leur calendrier. La boucle standard est emit + inspect : déployez le scout en direct, laissez-le émettre, et calibrez contre ce qui arrive réellement.

1. Déployez le scout (le défaut emit=true) avec un court run_interval_minutes pour qu'il s'active bientôt — définissez-le à la création via posthog:signals-scout-config-create {"skill_name": ..., "run_interval_minutes": 10} juste après llma-skill-create, plutôt que d'attendre le coordinateur auto-enregistre un défaut horaire.
2. Après un tick, lisez ce qu'il a fait : posthog:inbox-reports-list (les findings qu'il a réellement émis), posthog:signals-scout-runs-list (résumés de runs), -runs-retrieve (raisonnement complet pour un run), et -scratchpad-search (la mémoire durable qu'il a écrite).
3. Affinez le corps — serrez le discriminant, ajoutez des disqualificateurs pour ce dont il a eu des faux positifs, corrigez l'étalonnage emit.
4. Une fois qu'il arrive sur les bons findings, restaurez l'intervalle à quelque chose de durable (horaire+).

Voulez-vous être extra prudent ? Définissez emit=false pour dry-run d'abord — créez le config avec emit=false via -config-create pour que le scout n'ait jamais un premier run en direct ; il s'exécute et enregistre ce qu'il aurait émis (visible via -runs-list / -runs-retrieve) sans écrire dans la boîte de réception. Inspectez, affinez, puis basculez emit=true. Cela vaut le coup pour un scout que vous vous attendez à être bavard, coûteux, ou haute-stakes ; sinon juste émettre et regarder la boîte de réception est le chemin plus rapide vers un scout calibré.

Les contributeurs repo obtiennent une boucle plus rapide — hogli sync:skill et le chemin run local du harness ; voir references/lifecycle-and-testing.md.

Pour lire ce que vos scouts font plutôt que de les modifier — surveiller la flotte, inspecter des runs individuels, la mémoire scratchpad, et évaluer la performance — utilisez la compétence compagnon en lecture seule exploring-signals-scouts. Gardez les deux en sync quand le scout config / run / scratchpad surfaces changent.

Barre de qualité pour un scout v1

• Un discriminant signal-vs-noise nommé, bon marché, ancré près du haut.
• Une quick close-out pour qu'un run silencieux soit peu coûteux (ne payez pas pour l'exploration profonde quand la surface surveillée est baseline ou absente).
• 2–4 explore patterns concrets avec les requêtes/outils réels à exécuter — points de départ, pas une checklist rigide.
• Disqualificateurs listant les bruits connus de ce projet (quirks mono-utilisateur, bursts d'env dev, entités allowlistées).
• Une section Decide calibrée contre le contrat emit (confiance ≥ 0,65 pour émettre ; dessous, écrivez la mémoire).
• Orientation Save-memory utilisant les préfixes scratchpad pour que le scout devienne plus intelligent à chaque run.
• Un corps lean (poussez la profondeur dans references/) — chaque ligne est un coût token récurrent à chaque run.