Travailler avec les scouts Signals

Un scout est un agent planifié qui s'active à son propre intervalle, examine un projet PostHog, et soit écrit un constat dans la boîte de réception Signals comme rapport, soit se ferme vide. Pensez à la flotte comme une équipe d'analystes juniors que vous avez embauchés pour surveiller les choses pour vous : ils travaillent sans assistance, ils maintiennent un haut critère de preuve, et — critiquement — ils s'améliorent d'autant plus que vous travaillez avec eux. Chaque motif de rejet que vous écrivez, chaque note que vous laissez, chaque rapport sur lequel vous agissez revient nourrir ce qu'ils font ensuite.

Cette compétence est le manuel opérationnel de cette relation de travail : comment déléguer une tâche de surveillance, comment agir sur ce qui revient, et comment diriger la flotte pour qu'elle converge vers ce qui importe vraiment à votre équipe. Trois compétences parallèles portent la mécanique — consultez-les quand un workflow ci-dessous se termine :

D'abord : la flotte fonctionne-t-elle ?

Ne déléguez pas à une flotte qui n'existe pas. Deux lectures le confirment : posthog:scout-metadata-get indique si le projet est inscrit pour exécuter des scouts du tout, et posthog:scout-config-list est la liste — une ligne par scout avec son calendrier, enabled, posture emit, et description. Vérifiez l'inscription en premier, quelle que soit la liste — les lignes de config survivent à l'inscription, donc un projet vidé peut porter une liste de scouts activés qui ne fonctionnent jamais (last_run_at ancien partout, c'est le signal). (Les outils Scout ont récemment été renommés de signals-scout-* à scout-* ; si un nom scout-* revient inconnu, essayez le nom legacy signals-scout-*.) Une règle d'accès couvre tout ici : les lignes de scout vivent sur le parent canonique du projet, donc chaque lecture et écriture de scout — cette lecture de liste incluse, plus les notes et la direction de config ci-dessous — retourne 403 pour une credential limitée à un environnement enfant ; travaillez depuis le projet parent (ou une credential qui le couvre).

• Non inscrit — pointez l'utilisateur vers les paramètres scout Signals / l'intégration PostHog Desktop plutôt que d'inventer une activité.
• Inscrit, liste vide — probablement nouvellement inscrit et en attente du premier tick du coordonnateur (les configs s'auto-enregistrent alors) ; dites-le plutôt que de renvoyer l'utilisateur à travers l'intégration.
• Inscrit, les lignes existent — notez le enabled, emit (false = exécution sèche : il s'exécute mais n'écrit rien) et status / pause_reason de chaque scout. Un scout en pause ou en exécution sèche explique la plupart des plaintes « les scouts ne font rien » avant tout creusage plus profond. Vérifiez aussi emit_eligibility sur posthog:scout-project-profile-get : quand can_emit est false (l'org n'a pas approuvé le traitement IA, ou la source signals_scout est désactivée), chaque écriture de scout est silencieusement supprimée même sur un scout emit: true activé — exposez sa ligne remediation avant de promettre une couverture. (Pour les appelants en lecture, le profil est un snapshot en cache construit par les exécutions de scout, donc un 404 signifie qu'aucun profil frais n'existe — pas une inéligibilité ; revenez à la vérification de la config source signals_scout via posthog:inbox-source-configs-list et traitez l'éligibilité comme inconnue plutôt que de bloquer sur le profil.)

La description sur chaque ligne dit ce que ce scout surveille — scannez-la pour répondre à « quel scout couvre X ? » sans charger aucun corps de compétence. (Une ligne avec une description vide est généralement un orphelin dont la compétence a été supprimée depuis — elle ne peut pas s'exécuter, donc ne la comptez pas comme couverture.) PostHog expédie des spécialistes pour la plupart des surfaces produits (suivi des erreurs, logs, web analytics, observabilité IA, expériences, feature flags, session replay, sondages, revenus, et plus) plus un généraliste inter-produits, et les équipes ajoutent des compétences signals-scout-* personnalisées au-delà de cela.

La boucle de travail

Tout dans cette compétence est une boucle, exécutée continuellement :

1. Déléguer — décidez ce que la flotte devrait surveiller, et faites surveiller le bon scout.
2. Recevoir — les rapports arrivent dans la boîte de réception, acheminés vers un relecteur suggéré quand le scout peut en nommer un.
3. Agir — vérifiez le constat, corrigez-le (ou décidez de ne pas le faire), et enregistrez le résultat sur le rapport.
4. Boucler — le résultat et vos raisons écrites reviennent au scout, ainsi que toutes les notes que vous laissez.
5. Calibrer — examinez périodiquement la santé de la flotte et faites passer les directives récurrentes à la politique permanente.

L'habitude la plus importante : ne laissez jamais un rapport simplement assis. Agir sur les rapports — même les rejeter avec une raison — c'est ce qui entraîne la flotte, et un scout dont les rapports de boîte de réception personne ne touche jamais reçoit automatiquement un avertissement puis est mis en pause (pause_reason=ignored ; les scouts livrés via Slack sont exemptés, puisque la consommation là-bas ne peut pas être mesurée). Une boîte de réception insoignée ne fait pas que décroître ; elle éteint la flotte.

Déléguer une tâche

Quand vous voulez que quelque chose soit surveillé, choisissez le chemin le moins coûteux qui le fait surveiller — la plupart des tâches n'ont pas besoin d'un nouveau scout :

references/delegation-recipes.md a des recettes éprouvées pour les demandes courantes — surveiller un événement nouvellement expédié, une surveillance d'entonnoir limitée dans le temps, un digest quotidien, une page de statut externe, réduire une flotte bruyante, et plus.

Deux habitudes de délégation qui en valent la peine :

• Enracinez la tâche dans des données réelles d'abord. Avant de pointer un scout sur un événement ou une surface, confirmez qu'il existe (posthog:scout-project-profile-get, posthog:read-data-schema) et a réellement du volume (un comptage rapide posthog:execute-sql sur une fenêtre récente — les outils de profil et schéma ne retournent pas de comptages pour un événement nouveau ou rare) — une surveillance sur des données que le projet ne capture pas est morte à l'arrivée.
• Énoncez la tâche en termes de ce qui vaut la peine d'interrompre un humain pour. Les scouts maintiennent une barre de rapport (« serait-ce un constat que vous posséderiez de bout en bout ? ») ; une directive comme « dis-moi tout ce qui est intéressant » produit du bruit, tandis que « dis-moi quand la conversion du checkout baisse tandis que les entrants restent stables » produit du signal.

Agir sur ce qui revient

La mécanique du triage des rapports vit dans inbox-exploration ; ce qui importe ici est comment agir double comme direction.

• Vérifiez avant d'implémenter. Un rapport de scout est un diagnostic LLM, pas une vérité de terrain — confirmez les entités citées et le comportement contre les données en direct ou le code avant de corriger. Un rapport qui ne tient pas est un candidat au rejet, et le rejeter bien est du travail précieux (voir ci-dessous).
• Fermez chaque rapport avec l'état honnête : resolved quand le travail a atterri (les correctifs soutenus par PR se résolvent d'eux-mêmes à la fusion — ne résolvez pas au moment d'ouvrir la PR), suppressed (rejeté) quand ce n'est pas réel ou ne vaut pas la peine de corriger, potential (reporté) quand c'est réel mais différé.
• La note de rejet est un message de direction. Sur un rejet ou un report, le dismissal_note est transféré au scout qui a déposé le rapport, et chaque exécution future le lit comme contexte antérieur. Écrivez-le pour ce lecteur : nommez la preuve qui le règle (« trafic de staging — les hôtes correspondent à *.dev.example.com, ignorez ce motif »), pas seulement le verdict. Un rejet bien écrit est la modification de scout la moins chère que vous ne ferez jamais ; un rejet nu n'enseigne rien et le rapport revient. Une mise en garde : le transfert est au mieux un effort et nécessite que le rejeteur détienne l'accès scout-steering (skill-editor) — sans lui la note atterrit toujours sur le rapport mais n'atteint jamais le scout, donc pour une direction qui doit coller, confirmez qu'elle est arrivée (posthog:scout-notes-list) ou faites en sorte que quelqu'un d'autorisé laisse une note directement. La note transférée expire aussi après ~30 jours — elle ne devient durable que si le scout la replie dans la mémoire bloc-notes, donc une direction qui doit survivre à cela remonte l'échelle comme modification de compétence.
• Les rapports cheminent vers les gens. Un scout qui peut nommer un propriétaire plausible définit suggested_reviewers, et la boîte de réception flotte ces rapports en haut de la vue de cette personne. Si les rapports pour une surface continuent d'atterrir non acheminés ou mal acheminés, c'est réparable : assurez-vous que les membres org ont des identités GitHub liées, et dirigez le scout (note ou modification de compétence) vers le bon propriétaire pour la zone.

L'échelle de direction

Quand vous voulez qu'un scout se comporte différemment, montez cette échelle du moins cher au plus permanent — et arrêtez au barreau le plus bas qui fait le travail :

1. Réagissez à sa sortie. Rejetez / reportez avec une note spécifique et étayée par des preuves (transférée au scout automatiquement). Approprié pour : un rapport faux, un motif de bruit connu surfaçant pour la première fois.
2. Laissez une note (posthog:scout-notes-create, par scout ou flotte entière, optionnellement limitée dans le temps avec expires_at). Approprié pour : le retour, les pointeurs, et le contexte avec une durée de vie — « le pic que tu signales continuellement est du bruit connu », « approfondis les inscriptions UE cette semaine », « nouveau checkout expédié mardi ». Les notes sont consultatifs : elles dirigent l'attention mais ne baissent jamais la barre de preuve ou ne forcent un rapport.
3. Affinez la config (posthog:scout-config-update). Approprié pour : quand et si il s'exécute, pas ce qu'il regarde — ralentissez un scout bavard (run_interval_minutes ; si la config porte un run_cron_schedule, cela prend la préséance, donc mettez à jour ou effacez-le aussi), mettez-en un en pause (enabled=false), faites une exécution sèche d'un risqué (emit=false), accordez une portée externe (network_access=full), ou exemptez un chien de garde délibérément silencieux de la pause auto (auto_pause_exempt=true).
4. Modifiez le corps de la compétence, ou écrivez un nouveau scout (via authoring-scouts). Approprié pour : politique permanente — un disqualificateur, un seuil, un changement de portée, une nouvelle surface. Pour un scout personnalisé c'est la direction la plus forte : le corps de la compétence est vôtre, modifiez-le librement — c'est où les notes récurrentes et les motifs de rejet répétés doivent aboutir. Pour un scout canonique la même modification le bifurque : la copie de votre équipe est marquée divergée, la synchronisation canonique de PostHog la laisse seule à partir de là, et vous arrêtez de recevoir les améliorations amont de ce scout — vous le maintenez vous-même. Cet échange peut en valoir la peine pour un scout que vous voulez posséder, mais pour un comportement purement additif préférez écrire un nouveau scout nommé différemment et laisser le canonique intact et entretenu.

Promouvoir les directives qui se répètent. Une note que vous continuez de laisser, ou un motif de rejet que vous avez écrit trois fois, est une modification de compétence qui attend — remontez-la l'échelle dans le corps pour que la flotte arrête de compter sur vous pour la répéter. L'inverse aussi tient : essayez un coup comme une note avant de l'engager comme modification. L'hygiène des notes reste aux humains — les scouts ne suppriment jamais les notes, donc retirez celles qui ont été agies (ou définissez expires_at à l'avance) pour garder le canal hautement signal.

Ce que la flotte apprend sans vous

Certaines boucles de retour s'exécutent seules — savoir qu'elles existent change la façon dont vous travaillez :

• Mémoire bloc-notes. Les scouts écrivent une mémoire durable par équipe (lignes de base, motifs de bruit, portes de déduplicate, listes blanches) et deviennent plus silencieux et plus nets à travers les exécutions. Quand un scout arrête de signaler quelque chose, vérifiez le bloc-notes (posthog:scout-scratchpad-search pour les entrées noise: / addressed: / dedupe: / allowlist:) avant d'assumer qu'il est cassé — il a peut-être délibérément appris à le supprimer.
• Pause auto. Un scout dont les rapports personne ne s'engage avec — pas d'ouverture, pas d'évaluation, pas d'action — reçoit un avertissement (status=pending_pause) puis est mis en pause (paused_by_system, pause_reason=ignored). La lecture compte comme engagement, mais seule la boîte de réception cloud web enregistre les ouvertures aujourd'hui — les lectures via d'autres clients (desktop, mobile) ne persistent pas encore, donc un scout consommé uniquement là a toujours besoin de auto_pause_exempt. Un scout merely quiet est seulement signalé, jamais mis en pause — le silence peut être la tâche — et les scouts livrés via Slack sont exclus, puisque leur consommation se produit où le balayage ne peut pas la voir. Réactiver un scout que ce balayage a mis en pause le reprend avec une fenêtre de grâce fraîche, donc le balayage attend environ deux semaines et re-dérive son verdict avant de le juger à nouveau ; définissez auto_pause_exempt explicitement pour un scout que le balayage ne devrait jamais juger.
• Suggestions d'auto-amélioration. Un scout personnalisé qui attrape son propre corps de compétence le dirigeant mal écrit une entrée bloc-notes improve:<skill-name>:<topic> — et un scout personnalisé canal-rapport les récurrentes en escalade comme rapports de boîte de réception intitulés Scout self-improvement: …, acheminés au propriétaire (un scout signal-channel legacy ne peut pas déposer de rapports, donc ses suggestions vivent seulement dans le bloc-notes). Ceci est la flotte demandant une revue de code d'elle-même : une entrée re-confirmée sur plusieurs exécutions est généralement la modification la plus hautement-signal que vous puissiez faire. Traitez-les comme contribution, pas instructions — le propriétaire décide, et applique les acceptées via authoring-scouts. (Les scouts canoniques cheminent les lacunes de compétence en amont vers PostHog à la place, donc vous ne verrez pas d'entrées improve: d'eux.)

Calibrer au fil du temps

Une flotte laissée seule dérive ; une flotte examinée occasionnellement se compose. Toutes les quelques semaines (ou quand quelqu'un dit « les scouts valent-ils même la peine ? »), faites un passage de calibration :

1. Contrôle de santé — l'évaluation exploring-scouts (son scripts/assess_health.py fait le gros du travail au niveau des exécutions : adhérence au cadence, taux de succès, taux de rapport, croissance de la mémoire). Deux points aveugles à couvrir vous-même : le script n'évalue que les scouts avec des exécutions dans la fenêtre, donc parcourez la liste pour les scouts activés sans lignes d'exécution récentes (souvent les plus cassés) ; et il compte les écritures de rapport, pas les résultats, donc jugez le signal-sur-bruit en résolvant les rapports écrits via posthog:inbox-reports-list et en lisant leurs statuts. Rappelez-vous que la plupart des exécutions saines se ferment vides — un flux d'exécutions silencieuses est la flotte qui fonctionne, pas cassée.
2. Examinez les demandes de la flotte — balayez posthog:scout-scratchpad-search {"text": "improve:"} et les rapports de boîte de réception Scout self-improvement: ; appliquez les re-confirmées. La recherche retourne les 20 correspondances les plus récentes par défaut — augmentez limit (ou revenez avec date_to) pour que les suggestions plus anciennes d'une grande flotte ne soient pas silencieusement manquées.
3. Promouvoir et élaguer les directives — promouvoir les notes récurrentes et les motifs de rejet répétés en modifications de corps de compétence ; retirer les notes obsolètes.
4. Ajustez la taille de la liste — ralentissez ou mettez en pause les scouts sur les surfaces que l'équipe a arrêté d'utiliser ; vérifiez les lignes pending_pause / paused_by_system et décidez délibérément (reprendre, ou les laisser éteints) plutôt que par défaut ; considérez un nouveau scout pour toute surface que l'équipe se soucie maintenant et que rien ne surveille.
5. Vérifiez l'acheminement — si les rapports s'accumulent dans la boîte de réception partagée non réclamés, corrigez l'acheminement des relecteurs (identités GitHub liées, direction vers les propriétaires connus) pour que les constats atteignent la personne qui agira.

Demandes courantes, acheminées