references/delegation-recipes.md
Delegation recipes
Worked recipes for the common "have the scouts do X for me" asks.
Each one follows the same discipline: ground the job in real data, pick the cheapest rung on the steering ladder that gets it watched, and set up the feedback loop so the watch improves.
Tool mechanics (exact call shapes, confirmation flows, config fields) live in authoring-scouts; this file is about choosing the right move.
"Watch this event I just shipped"
A new custom event ("checkout_v2_completed", "ai_summary_generated") that no canonical scout knows about.
- Confirm the event actually captures:
posthog:read-data-schemafor its shape, a quickposthog:execute-sqlfor volume. No data yet? Wait until it flows — a scout can't baseline an empty stream. - Check the roster (
posthog:scout-config-listdescriptions): if the event belongs to a surface a specialist already watches (an error, a survey response, a flag call), a note telling that scout about the new event is enough. - Otherwise author a custom single-event scout via
authoring-scouts— the custom single-event pattern in itsreferences/scout-patterns.mdis the template. Give it a real discriminator ("volume drops >50% against the trailing week while site traffic holds") rather than "watch for anything odd".
"Tell me if errors / logs / traffic spike"
Almost always already covered — the canonical fleet ships anomaly watchers for error tracking, logs, web analytics, and most other surfaces.
- Find the specialist in
posthog:scout-config-listand confirm it'senabledwithemit: true— and that the project can emit at all (summary.emit_eligibility.can_emitonposthog:scout-project-profile-get; when false, writes are silently dropped fleet-wide; a 404 just means no fresh cached profile, so fall back toposthog:inbox-source-configs-listand treat eligibility as unknown). - If the ask has a specific edge ("especially the checkout service", "only production"), leave the scout a note with that focus.
- Only escalate to a skill edit if the scout structurally can't see what you care about (wrong threshold, missing disqualifier) — and it keeps proving that across runs.
"Keep an eye on X this week" (time-boxed focus)
The textbook note use case — no authoring at all:
posthog:scout-notes-create
{
"content": "We think the EU signup funnel regressed after Tuesday's deploy — prioritize it this week. Baseline: ~4.2% visitor→signup.",
"skill_name": "signals-scout-product-analytics",
"expires_at": "<ISO date ~1 week out>"
}
expires_at makes the note self-retiring, so the channel stays clean without anyone remembering to delete it.
Omit skill_name to address the whole fleet — right when you don't know which scout will hit the surface first ("we migrated auth providers Monday; treat auth-adjacent shifts as suspect").
"Give me a daily digest of what's happening"
Wanting a rhythm, not a new detector. Two options, cheapest first:
- Most scouts already run daily (default
run_interval_minutes: 1440) and write only when something clears the bar — so the inbox is the digest. Check the user isn't actually asking for a triage habit (inbox-explorationeach morning). - If they genuinely want a roll-up report every day regardless of anomalies, that's the daily digest / roll-up pattern in
authoring-scouts'references/scout-patterns.md— a custom scout that summarizes rather than detects. Reading counts to the auto-pause sweep: opening a report in the inbox (or rating it) is recorded as consumption, so a digest people actually read won't look ignored. Reserveauto_pause_exemptfor a digest consumed somewhere the inbox can't see (forwarded, read via a client that doesn't record opens).
"Watch something outside PostHog" (vendor status page, docs, a competitor)
Scouts run in a sandbox that defaults to a trusted-domain allowlist (PostHog, GitHub, package registries).
- If the external data already syncs into the data warehouse (Slack, a CRM, billing, support), point a scout at the warehouse table — the warehouse-backed source pattern — with no network change needed. Prefer this path whenever it exists: the scout stays inside the trusted allowlist.
- For genuinely external reads (a status page, arxiv, a changelog), author the custom scout and set
network_access: "full"on its config. The change applies from the next run and is activity-logged. Scout configs live on the project's canonical parent — a credential scoped only to a child environment gets a 403 on this write, so make (or request) the grant from the parent project. Treatfullas a real grant, not a convenience: the scout reads external content that may try to steer it (prompt injection) while it holds project read tools and open egress. Reserve it for sources you trust, name the exact sites in the skill body and tell the scout to treat everything it fetches as untrusted data rather than instructions, and keep the rest of the fleet on the defaulttrustedallowlist (a per-scout custom domain allowlist doesn't exist yet).
"The scouts are too noisy"
Diagnose which scout, then climb the ladder — don't pause the fleet wholesale.
- Find the offender: report rates per scout via
exploring-scouts(near-100% of runs writing is the tell), or just look at who filed the reports being ignored. - Dismiss the noise well. Dismissal notes are forwarded to the filing scout (when the dismisser has scout-steering access) — three specific notes ("staging hosts", "known crawler", "internal test org") often quiet a scout with zero editing.
- Still noisy? A note stating the pattern generally ("traffic from
*.dev.example.comis ours, never report it"). - Structurally noisy? Edit the body via
authoring-scouts: add the disqualifier, raise the threshold. - Right signal, wrong volume? Slow it down:
posthog:scout-config-updatewith a largerrun_interval_minutes— and if the config has arun_cron_schedule, clear or update it too, since a cron schedule takes precedence over the interval. Pause (enabled: false) is the last resort — a paused scout learns nothing.
"The scouts never find anything"
Quiet is often correct — most runs should close out empty. Before loosening anything:
- Confirm the project is still enrolled (
posthog:scout-metadata-get— config rows outlive enrollment, so a full-looking roster can belong to a drained fleet), that the fleet is actually on (posthog:scout-config-list:enabled,emit— dry-run scouts write nothing), and that runs execute (exploring-scoutshealth check). - Read a few run summaries: a scout narrating "surface at baseline" is working; if it keeps saying "no data for X", the watched surface may not capture data (
posthog:scout-project-profile-getshows what's in use). - Only then consider the bar: a threshold edit via
authoring-scouts, or a note pointing at what the team considers report-worthy that the scout is skipping. - Check the inbox default view isn't hiding output: suppressed reports (judged not-actionable) don't surface —
posthog:inbox-reports-listwithstatus: "suppressed"plus thescout: "<skill_name>"filter shows whether this scout is finding things that get filtered (without the scout filter you'd be reading the whole project's suppressed reports).
"Get reports to the right person"
Reports reach people via suggested_reviewers — the inbox floats a report to the top of the suggested reviewer's own view.
- A reviewer is a PostHog user, identified by
user_uuid(any org member) or bygithub_login(matched against the member's linked GitHub identity). Auser_uuidreviewer needs no GitHub link; a login-only reviewer matches nobody until that member links the account, so resolve a name or a login to auser_uuidbefore routing on it: inside a run a scout usesscout-members-list, which is a sandbox-only tool; from your own agent useposthog:org-members-list(andposthog:org-member-get-github-loginfor the linked login), which need theorganization_member:readscope on a scoped credential; without it, ask the user for the person's PostHog user UUID or route bygithub_loginwhen the account is linked. That list is visibility-filtered: unless you are an organization admin or the organization lets members see each other, it shows only you and the members who share a project with you, so a missing name is not proof the person does not exist. The reviewer write still accepts any org member, so on a project with restricted access confirm the person can open the project first (the project access tools, not the member list, answer that); a reviewer who cannot see the report is effectively unrouted even though the report looks assigned. - If a surface's reports keep landing unrouted, teach the fleet the owner: a note ("checkout belongs to Dana; route checkout findings to her"), or for permanence, the owner map in the scout's body.
For a rule that spans scouts, leave a fleet-wide note (
posthog:scout-notes-createwith noskill_name), which every scout reads. Thepipeline:report-researchaudience reaches only the stage that researches and routes reports built from clustered signals; a scout that authors reports directly sets its reviewers itself and never reads it. Scouts cache confirmed owners asreviewer:scratchpad entries, so one good steer compounds. - A live report routed to no one isn't stuck: a scout (or you, via the report tools) can set reviewers on it after the fact, and that correction is forwarded to the scouts involved as a note when the reviewers carry GitHub logins, so fixing the report is itself a steer.
"Send this scout's reports to Slack"
Delivery is a config decision, not an authoring one: a surfaced report (ready or pending_input) goes to the inbox and to Slack, while a report the safety or actionability judge suppressed stays inbox-only, so a missing Slack message for a suppressed report is not a delivery failure.
posthog:scout-config-updatewithoutput_destinations.slack: the workspaceintegration_idplus either achannelor up to fiveusersto DM, never both (field shapes and the threading option are inauthoring-scouts, Run posture). From a scoped API key or OAuth token this write also needsintegration:readandtask:read(or the write scopes) alongsidesignal_scout:write; a minimally scoped credential gets a permission error. Read the existingoutput_destinationsfirst and send the whole object back; the update replaces it, so sending onlyslackdrops an existingwebhookpointer.- Slack delivery is a firehose of that one scout's output (no priority filter, no reviewer routing), so it suits a scout whose bar is already tight. Calibrate in the inbox first, then add the destination.
- A Slack-delivered scout is exempt from the ignored-reports auto-pause (consumption in Slack isn't measurable), so the fleet won't switch it off for you; review it yourself in the calibration pass.
"Try a risky watch safely"
For a scout you expect to be chatty, expensive, or high-stakes:
- Create it with both
enabled: falseandemit: falsein the nested config atposthog:scout-createtime.emit: false(dry-run) makes it log what it would report without touching the inbox;enabled: falsematters too, because a fresh enabled config on a rolling interval has nolast_run_atand the coordinator treats it as immediately due; it could burn a scheduled run (or 409 your manual one) before your controlled test. (Arun_cron_scheduleanchors on the config's creation time and waits for its first slot, so a cron scout isn't immediately due, but disabling it is still the safer default.) - Spend one
posthog:scout-run-now(it works on a disabled scout), then read the run viaexploring-scoutsto see what it would have written. Pass anoteon that call to point the test run at the case you want exercised ("focus on yesterday's checkout drop") without leaving a durable note behind. Runs are metered against the project's daily budget — dogfood the queries by hand for iteration and save real runs for end-to-end checks. - Calibrate, then set
enabled: trueandemit: true, and let the normal act-and-feed-back loop take over.