AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

exploring-scouts

How to explore and make sense of PostHog Signals scouts — the scheduled agents that scan a project and write reports into the Signals inbox. Use when a user wants to understand what scouts they have, how each one is behaving, and whether the fleet is actually working. Covers surveying the fleet and its schedules, reading recent scout runs and drilling into a single run's reasoning, inspecting the durable scratchpad memory the fleet has built up, tracing a run to the reports it wrote or edited, reading the follow-up checks still measuring a report, and assessing a scout's health and performance over time (cadence, success rate, report rate, signal-to-noise). Read-only and exploratory — to write or tune a scout, use `authoring-scouts` instead. Trigger on "what are my scouts doing", "how is my <x> scout performing", "show me recent scout runs", "why did this scout find/report nothing", "what has the fleet learned", "explore scout run <id>", "is my scout working".

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read posthog--exploring-scouts at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 3

references/scout-data-model.md

Scout data model — what you're reading

Three records describe a scout's life on a project, plus one snapshot it orients from. This reference is the vocabulary for everything exploring-scouts returns.

SignalScoutConfig — the scout's settings

One row per (team, skill_name). Returned by scout-config-list. This is the scout's control surface, separate from its instruction body (the LLMSkill).

| Field | Meaning | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Config id: the handle scout-config-update takes to tune it. | | skill_name | The skill this config controls. Fixed; one config per skill per team. Usually signals-scout-*, but any skill name can hold a config. | | display_name | The name the UI shows. Blank means the default derived from skill_name. | | description | What the scout watches, read live from the skill's frontmatter. Empty when the skill is gone from the team (an orphan config) or has no description. | | scout_origin / owners | canonical (PostHog seeded it) or custom (team-authored); owners lists the skill's owners. The value comes from the skill row's seed metadata, which survives an in-place edit, so a canonical scout the team has edited (diverged, no longer synced) still reads canonical here. | | enabled | false = paused. The coordinator skips disabled scouts entirely. Derived from status. | | status | Who owns the pause: active, pending_pause (still runs; an ignored warning pauses after a week, a no_output warning only ever warns; any config edit clears it), paused_by_system (automatic, resumable with enabled: true), paused_by_user (a person switched it off; the system never overrides it). | | pause_reason | Why the system paused or warned: no_output, ignored, or repeated_failures. Null outside pending_pause / paused_by_system. | | status_changed_at | When status last changed: for pending_pause, when the warning was issued (an ignored warning pauses about a week later; a no_output one never does). | | consecutive_failure_count | Current streak of failed scheduled runs (manual and workflow-triggered failures don't count; a clean run from any trigger clears it). The failure breaker (repeated_failures) trips one failure past the runs the schedule fits in twelve hours, clamped to 5–25 (daily: 5, rolling hourly interval: 13, hourly cron: 15 because cron slots are counted over a DST-padded window); any config edit resets it. | | auto_pause_exempt | true = the inactivity sweep never judges this scout (for a watchdog whose silence is the job, or output consumed where the inbox can't see it). | | emit | false = dry-run: the scout runs and reasons every tick but writes nothing to the inbox. | | run_interval_minutes | Rolling cadence, 30–43200. Default 1440 (daily). The coordinator dispatches when due. | | run_cron_schedule | Optional five-field cron in the project timezone. When set it takes precedence over the interval; a new or edited schedule waits for its next slot rather than catching up. | | output_destinations | Where reports go besides the inbox: slack (integration plus a channel or up to five DM targets, optional thread_reports) is the only destination Signals delivers to itself; a webhook entry is a pointer to a CDP destination the owning product manages, and says nothing about whether anything is delivered there. | | network_access | What the run's sandbox can reach: trusted (default: the platform's trusted-domain allowlist: PostHog, GitHub, package registries) or full (any site, for skills that read external docs/papers). | | mcp_gateway_server_ids | MCP store servers the scout's runs may mount, from connections shared with the whole team. Empty = no shared servers (where gateway enforcement is not yet active, the acting user's personal connections may still mount). Security-relevant like network_access, and activity-logged. | | write_scopes | Project-wide write scopes this scout holds (notebook:write, dashboard:write, insight:write, annotation:write, alert:write, customer_task:write, llm_skill:write, warehouse_view:write, warehouse_table:write, replay_scanner:write, canvas:write, experiment:write). New scouts start with notebook:write. Empty = read-only beyond findings and memory. A dry run never holds them. | | model | Pinned model for this scout's runs, or null to follow the fleet default. Setting one needs the scouts-model-config early-access flag on the project. | | structured_output_schema | Optional JSON Schema (object-rooted) describing one structured record the scout produces via scout-record-output. Null = the structured-output channel is off (it also needs emit on). When set, each run is shown the schema and its records are validated against it and recorded as $scout_structured_output events. | | tags | Free-form kebab-case labels (up to 10) grouping the fleet; scout-config-list filters on them. | | source_product / source_id | Set when another product stood the scout up for one of its own objects (Replay Vision creates one per scanner) so it can find and clean up its scouts; null for a scout a person created directly. | | last_run_at | When the coordinator last dispatched it. null = never dispatched by the coordinator, not never run: manual (scout-run-now) and workflow-triggered runs leave it untouched, so check scout-runs-list before calling a scout never-run. Drives the due-check (with run_cron_schedule and creation time on a cron scout). |

The replay_scanner:write grant permits scanner maintenance across the project. Scouts must set a credit limit on scanners they create, copy, or enable. Changes to targeting, sampling, or the model of an enabled scanner also require a limit. Scouts cannot remove a limit, delete a scanner, or start manual scans, retries, or backfills. They can disable a scanner and keep its observations. Shared ratings must record explicit user verdicts. Autonomous assessments belong in scout memory or reports. | updated_at | When the config last changed, including settings edits and system status changes. Scheduled dispatch updates last_run_at, not this field. |

A scout that is enabled: true, emit: false is alive and working — it just can't post reports. It is the extra-careful rollout posture for a chatty or high-stakes scout (the default is emit: true), and the most common cause of "my scout does nothing" reports.

SignalScoutRun — one execution

Returned by scout-runs-list (summary) and scout-runs-retrieve (detail; same shape). Each run is one sandboxed agent execution of one scout. The run is a thin bridge to a tasks.TaskRun — status, timing, and the full transcript live on the Task side.

scout-runs-retrieve takes the run id as id, not run_id — even though the list and the detail payload both name the field run_id. Pass the list's run_id value through as id.

| Field | Meaning | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | run_id | UUID of the run. Pass it to scout-runs-retrieve as id. Strictly team-scoped (404 across teams). | | skill_name | Which scout ran. | | skill_version | The body version that ran. If a scout was edited, older runs ran an older version — useful when comparing behavior before/after a change. | | status | Run outcome, from the linked TaskRun (see below). | | started_at | ISO-8601 — when the TaskRun was created. | | completed_at | ISO-8601 — when it finished. null while in flight. Duration = completed_at - started_at. | | emitted_report_ids | The reports the run authored via emit_report, in order. This (with edited_report_ids) is the run's output — resolve each id via inbox-reports-retrieve. Empty = the run authored nothing, except on a measurement scout, whose output is its $scout_structured_output records.