Authoring Signals scouts
A scout is a scheduled agent that wakes on its own interval, looks at one Flind project, decides what's genuinely worth surfacing, and writes it into the Signals inbox as a report — or closes out empty, which is a real outcome.
Flind ships a fleet of canonical scouts (a cross-product generalist plus per-surface specialists).
This skill helps you and your agent adapt those canonical scouts to a specific project, or author new scouts from scratch for a use case the fleet doesn't cover.
A report-producing scout's output is the report channel: it lists emit_report / edit_report in its frontmatter allowed_tools and authors or edits full inbox reports 1:1 directly.
Most of the canonical fleet runs this way, and every new report-producing scout should too — include the allowed_tools opt-in when you author one.
A scout whose output is a product surface (for example, suggestions on a workflow page) omits both tools; see Scouts with a product-specific output.
Where that output lands is a separate, per-scout config decision: the report goes to the Signals inbox, and the same report can be delivered to a Slack channel or DM at the same time (output_destinations under Run posture) — so don't rule a scout out of a job because the user wants the result in Slack.
(A historical signal-emitting channel — weak emit-signal findings a pipeline consolidated — still exists in the harness for scouts that never opted in, but it is deprecated: don't author new scouts on it, and opt an old one in rather than extending it.)
A scout is an LLMSkill that holds a SignalScoutConfig.
The harness loads the body verbatim as the agent's system prompt, and progressively reads any bundled reference files on demand.
The config row is what makes a skill a scout. Any valid skill name works, so the signals-scout- prefix is optional.
The prefix controls one thing: the coordinator globs signals-scout-* to auto-register a config for a skill that has none.
A skill with any other name needs its config created alongside it, which is what scout-create does.
The job before the writing
Don't write a scout in the abstract.
Ground it in the target project first — a scout is only as good as its fit to the data it watches.
(The scout tools were recently renamed from signals-scout-* to scout-*; if a scout-* name comes back unknown, the server may still expose it under the legacy signals-scout-* name — search the tool catalog and call whichever name it returns.)
- Read the project.
posthog:scout-project-profile-get returns the deterministic snapshot the scout itself cold-starts from: products in use, top events with reach/burst metrics, integrations, existing inbox counts.
If the scout watches a specific event, confirm it exists and check its shape with posthog:read-data-schema.
A scout for an event the project doesn't capture is dead on arrival.
- See what already runs.
posthog:scout-config-list lists every existing scout on the project with its schedule, enabled, and emit posture, plus each scout's description (pulled from the skill's frontmatter) so you can tell what a scout watches without loading its body.
Don't duplicate a surface a canonical scout already covers — adapt that one instead.
- Read the closest canonical scout. It's your template and your reference shape.
Pull it with
posthog:skill-get {"skill_name": "signals-scout-<x>"} (per-team rows) or read it from the repo at products/signals/skills/signals-scout-*/.
The generalist (signals-scout-general) is the broad template; if your scope is domain-tight, pick the specialist closest to your surface — list the live roster with posthog:skill-list {"search": "signals-scout"} (specialists exist for most product surfaces: error tracking, logs, AI observability, experiments, feature flags, session replay, web analytics, surveys, and more).
- Skim the inbox.
posthog:inbox-reports-list shows what reports are actually landing — calibrate so your scout adds signal, not noise.
Choose the path
There are two independent decisions: what you're building, and where it lives.
What
| Situation |
Approach |
| A canonical scout is close but too broad / too noisy / missing a disqualifier for this project |
Adapt it — narrow the scope, add disqualifiers, retune thresholds. |
| You want a surface no canonical scout covers (a custom event, a product-specific funnel) |
New scout from scratch — copy the closest canonical scout as scaffolding, replace the domain discriminator + explore patterns. |
| You want to compare prompts, models, or reasoning efforts before applying a change |
Private trial — keep the saved scout intact, review its rubric, and compare variants through the Test loop below. |
| You only want to change when / whether a scout runs |
No authoring — just tune the config (see Run posture). |
| You have one-off feedback, a pointer, or short-lived context for a scout |
No authoring — leave a note (see Steering with notes). |
Where
| Path |
Mechanism |
Use when |
| Per-team (the common user path) |
Create a new runnable scout via posthog:scout-create; edit its prompt or files later via posthog:skill-update / -file-create, and tune its runtime config via posthog:scout-config-update. |
Customizing for one project. The harness globs the row in on the next tick; canonical sync leaves your edited ("diverged") row alone. |
| Canonical (Flind contributors) |
Edit disk under products/signals/skills/signals-scout-*/, lint/build, open a PR. |
Improving a scout for every enrolled project. lazy_seed mirrors it onto all enrolled teams on the next tick. |
Adapting-in-place tradeoff: editing a canonical scout's row for your team marks it diverged — you stop receiving upstream improvements to that scout.
If you only need an additional behavior, prefer authoring a new, differently-named scout (signals-scout-<your-scope>) and leaving the canonical one intact.
See references/lifecycle-and-testing.md for the exact skills-store calls, the build/lint commands, and how seeding works.
Write the scout
First pick the shape.
references/scout-patterns.md is a cookbook of the reference architectures scouts fall into — anomaly watcher, liveness/absence watcher, zero-result/unmet demand, watchlist explore/exploit, cross-product correlation, recommendation/gap, warehouse-backed source, custom single-event, open-text theme, adversarial/abuse concentration, external-tool/code, state∩code intersection, custom issue-tracker/work-queue, daily digest/roll-up, triage over a pre-detected stream, first-person dogfooding/probe, recurring measurement/LLM-judge, maintainer/steward, owner-scoped book/queue, trigger-to-brief enrichment, dispatcher/campaign, fleet meta-scout/reviewer — each mapped to a canonical scout or a proven custom shape you can copy as scaffolding.
It also makes the key point that a scout can watch any source Flind ingests into the data warehouse, not just analytics events (a Slack channel sync, a billing system, a CRM, a support inbox), plus external systems reachable from the sandbox, other agents' output, and the scout fleet itself.
And where a built-in signals source already covers the surface (GitHub and Linear issues), the issue-tracker pattern says where that source stops and a scout starts paying for itself.
A scout does not have to stop at describing a fix: the maintainer / steward pattern is how a scout holding write_scopes keeps a family of dashboards, alerts, warehouse views, or scanner prompts healthy itself, with a write ladder that says which changes it applies, which it verifies and reports, and which it hands to a human.
Find the closest pattern, then write the body.
Follow references/scout-anatomy.md — it has the frontmatter schema (including the allowed_tools report-channel opt-in every report-producing scout needs; a scout with a product-specific output omits it), the canonical body structure (quick close-out → orient → domain discriminator → explore patterns → save-memory → decide → disqualifiers → close-out), the lean-body rule, and copy-ready skeleton templates for both a specialist and the generalist.
Write the body feature-forward. The body is a prompt a run reads in full, every run, for as long as the scout lives — so it states what the scout watches and how it decides, and nothing else. Four things do not belong in it:
- No rollout state. A preview flag, an early-access gate, a "recently renamed" tool, a port that is happening one scout at a time. It is true this month and misleading next month, and a run cannot tell which. Write the behavior the scout should follow now; if a capability may be absent, say how the run tells, not when it is due.
- No backlog. Work that is planned, a field that does not exist yet, a lane somebody means to add. A run cannot act on it, so it only spends tokens and invites the run to wait for something.
- No project-only facts. A metric, dashboard, event, id, or reviewer that exists in one project. A canonical scout ships to every project, so a fact from one of them is wrong for almost every run. Text about an optional product says how the run tells whether the project uses it, and never assumes it does.
- No duplicated harness mechanics. The report-channel contract, the run gates, and the close-out format come from the harness prompt, which every report-channel scout is given. A copy in the body drifts from the real one and the run then holds two versions of the same rule. Keep the body to your scout's own domain framing.
The same four apply to a bundled reference: it is read at run time too, so it carries no more rollout state or backlog than the body.
Two craft references the whole fleet reasons in terms of — a good scout's Decide and memory sections are built on them, so read them before writing those sections:
references/report-contract.md — the report tools (scout-emit-report / scout-edit-report), the report bar (author 1:1 only for a finding you'd own end-to-end), suggested_reviewers routing, the dedup-via-report_id discipline (the channel isn't idempotent — reconcile against existing reports via the vanilla inbox-reports-list / inbox-reports-retrieve before authoring), and the accepted caveat that the pipeline may later rewrite an authored title/summary.
This is how your scout decides what clears the bar and how to file it.
references/dedupe-and-memory.md — the four-states classifier (net-new / material-update / already-covered / addressed-or-noise), the scratchpad key-prefix vocabulary, and the cross-project noise patterns.
This is how your scout avoids re-filing and learns across runs.
references/report-checks.md — the follow-up checks a scout attaches to a report so "did the fix hold?" is measured later instead of remembered.
This is how your scout closes the loop on a finding after somebody acts on it.
A report is backward-looking; a check is the opposite direction — an expectation plus a time to test it, written onto a report with scout-report-check-create.
Give your scout a checks section when its findings are the kind whose fix shows up in data later.
Three rules belong in the body, and the reference has the rest:
- List the report's existing checks first (
scout-report-check-list), every time. An open check for the same claim makes a second one noise, and a report holds at most five open checks.
metric_threshold wherever one number settles the claim and an event or action series can carry it. The coordinator measures it itself, with no scout run.
agent when no single number settles it, or when the number lives outside events — a log rate, a fix whose effect shows in which entities fire rather than how many, a claim that needs a stack trace read.
The single most important design decision in any scout is its signal-vs-noise discriminator — the cheap profile-shape read that separates "worth investigating" from "baseline".
For error tracking it's the count vs distinct_users ratio; for CSP it's reach over raw count.
Your new scout needs its own.
Name it explicitly near the top of the body so every run anchors on it.
(The one exception: a measurement scout on the structured-output channel holds no bar — it applies a rubric to every sampled item, and the rubric takes the discriminator's slot as the design surface to name, dogfood, and calibrate. See the recurring measurement / LLM-judge pattern in references/scout-patterns.md.)
A second design consideration applies to a metric-shaped scout — one that scores, ranks, or reports a named, reusable measure, whether a business measure (MRR, churn risk, usage revenue, activation) or operational telemetry it computes every run to monitor or report (cost per run, failure or error rates, latency, throughput).
If the project has an approved metric for that measure (metric-list shows what exists), name it in the body and run it with data-catalog-metric-run, so the scout's number matches the one the team already reports.
Run posture (config)
A scout's schedule and emit behavior live on its SignalScoutConfig, separate from the skill body.
For a brand-new scout, pass these settings in the nested config object of the posthog:scout-create call, including creating it disabled or in dry-run before it ever runs.
When creating a scout to test an idea, set config.enabled=false so scheduled runs cannot interfere with the trial.
The endpoint creates the skill and config atomically, always opts the scout into the report channel, and safely re-applies config fields when the same definition is retried.
A scout with a product-specific output must stay off the report channel, so create it with skill-create and scout-config-create instead; see Scouts with a product-specific output.
Otherwise the coordinator auto-registers an enabled config on the default every-24-hours schedule on its next tick (up to ~30 min).
For an existing scout, tune with posthog:scout-config-update (find the id via -config-list):
run_interval_minutes — 30 to 43200.
Default 1440 (every 24 hours).
Slow a chatty or expensive scout by raising this.
run_cron_schedule: a five-field cron expression ('30 9 * * *', '0 9 * * 1-5') evaluated in the project's timezone; occurrences must be at least 30 minutes apart.
When set it takes precedence over run_interval_minutes, so a "slow it down" edit on a cron scout has to change or clear the cron (set null to return to the rolling interval).
A new or edited schedule anchors on the edit time and waits for its next slot rather than catching up on a past one.
Reach for it when the run should land at a wall-clock time: a digest before standup, a weekday-only watch.
- A scheduled run starts inside a window, not at an exact minute.
Each scout has a fixed offset in that window, so its cadence does not change from run to run.
A cron scout starts within 20 minutes of its cron time, so a
0 9 * * * scout starts at the same minute between 9:00 and 9:20 every day.
An interval scout starts within the same 30-minute coordinator tick, and last_run_at records the tick, not the start.
A scout's first run, a manual run, a workflow run, and a report-check run start at once.
When you explain or write a schedule, describe the time as a window.
enabled — false pauses the scout entirely (coordinator skips it).
precheck_query — defaults to null: a HogQL SELECT that a scheduled run evaluates before it starts, with {since}, {now}, and {interval_minutes} placeholders.
No rows, or one row with one false value (such as a zero count()), skips the run before it creates a run row or a sandbox. Any other result starts the run, and the rows enter the run prompt. A query error also starts the run.
Only scheduled runs evaluate it: a manual, workflow, or report-check run always starts.
Set it for a scout that has nothing to do on most ticks. Test the query with posthog:scout-config-precheck-test before you save it, because a scheduled check runs as the scout's acting user and the dry run runs as you.
A canonical scout can ship a default in its scout-precheck-query frontmatter. precheck_query overrides that default, null restores it, and precheck_disabled: true turns off both.
The full recipe, the placeholder semantics, and how to diagnose a tick with no run row are in references/scheduled-precheck.md.
emit — defaults to true: the scout writes its reports straight to the inbox.
Set emit=false (dry-run) to inspect an ordinary run's reasoning without publishing reports to the inbox.
Private trials capture reports and memory separately and work while the source scout is paused or has emit=false.
network_access — defaults to trusted: the scout's sandbox can only reach the platform's trusted-domain allowlist (Flind, GitHub, common package registries), which covers the MCP loop and gh but blocks everything else.
Set full for a scout whose skill needs to read arbitrary external sites, e.g. documentation, papers on arxiv.org, or a vendor status page.
Applies from the scout's next run, and changes are activity-logged.
auto_pause_exempt — defaults to false.
A scout whose reports nobody engages with (no open, rating, or action — the cloud web inbox records reads; other clients don't yet) is warned and then paused automatically (pause_reason=ignored) — every run costs a sandbox agent, so a scout producing output no human consumes shouldn't keep running forever. A scout that is merely quiet is only flagged (pause_reason=no_output, a warning that never advances to a pause), since a watch scout's silence can be its job.
-config-list shows the warning as status=pending_pause and the pause as status=paused_by_system; setting enabled=true again resumes the scout with a fresh grace window before the sweep may judge it again.
Set auto_pause_exempt=true up front for a watchdog scout whose whole job is to stay quiet, so it never even picks up the quiet flag.
write_scopes — defaults to ["notebook:write"]: the scout reads the project and writes its findings, its memory, and notebooks.
notebook:write reaches every notebook in the project, not only the ones the scout made. Send [] (or drop it from the list) for a scout that should write nothing but its findings and memory. Unlike the other scopes, a run keeps it when its author no longer resolves and it acts as another project member.
Grant 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, or experiment:write to a scout whose job is to maintain one of those things rather than only describe what it would change.
The body of such a scout follows the maintainer / steward pattern in references/scout-patterns.md: a curated inventory, a write ladder (do-and-log, do-verify-report, hand-to-a-human), a per-run change cap, and a rolling maintenance report naming every object changed.
Each scope is project-wide and covers update and delete of every object of its kind, not only the ones the scout made, so grant only what the scout's body actually tends, and say in the body what it may change and when.
llm_skill:write is the one to think twice about: custom scouts are skills in the same store, so a scout holding it can edit a sibling scout's body, or the body it runs from itself. Grant it to a scout whose job really is tending a set of skills, name that set in the body, and say there that the scouts are off limits unless tending them is the job.
warehouse_view:write and warehouse_table:write are separate on purpose: a scout that keeps a set of views healthy does not also need to create tables. Take both rows only when the scout tends both.
replay_scanner:write permits scanner maintenance. A scout must set a credit_limit when it creates, copies, or enables a scanner, and before it changes targeting, sampling, or the model of an enabled scanner. It cannot clear a limit, delete a scanner, or start manual scans, retries, or backfills. Use enabled: false to stop a scanner and keep its observations. Change a shared rating only to record an explicit user verdict, because ratings steer how the scanner judges later sessions.
customer_task:write covers every Customer analytics task in the project, including tasks assigned to other people: create, update (status, due date, assignee), archive, and restore archived tasks, with no delete. Say in the body whose tasks the scout tends, and whether it may reassign one.
Customer analytics tasks are still behind the customer-analytics-customer-tasks feature flag. On a project without it the task tools do not exist and the grant does nothing, so do not grant it there.
canvas:write reaches every canvas in a public space and every canvas the acting user created: publish, layout, runtime state, and soft-delete of the acting user's own canvases. A scout run cannot create a canvas, because a scout task has no space to file one in. Create the canvas first, name its id in the body, and follow the one-canvas maintainer variant in references/scout-patterns.md. Each published version records the run's task, so version history shows which run published it.
experiment:write is the one grant that changes what end users see. It reaches every experiment in the project: create, edit, duplicate, archive, launch, pause, resume, end, and reset. Launch and pause turn the linked feature flag on and off. A scout cannot delete an experiment, copy one to another project, migrate a legacy one, or open a flag cleanup pull request. Without feature_flag:write, which no scout can hold yet, it also cannot ship a variant or change the variants, rollout, or holdout once an experiment has launched or its flag is on. So a scout sets up drafts and ends experiments, and a person ships them. Say in the body which experiments the scout tends, and which lifecycle changes it may make without a person asking.
Only the person the scout's runs act as (whoever authored it) or a project admin can set the field, and grants are activity-logged. A scoped API key must itself carry each scope it grants.
A granted scout is told in its run prompt which objects it may change, and is asked to name every change in its close-out. The grant is an upper bound: the acting user's own permissions still apply to each object, and the scout reports a refused write rather than retrying it.
A dry run (emit: false) never holds the grant, so a scout can be previewed without it changing anything.
To audit the writes after a run, see "Auditing what a scout changed" in working-with-scouts: the changes land in the activity log under the scout's acting user, tagged "via MCP", with no scout or run name on the row.
Applies from the scout's next run.
output_destinations — defaults to none.
When adding Slack to an existing scout, first read output_destinations, then send the full object with every key preserved. Updates replace the object, so sending only slack removes an existing webhook pointer.
Set slack to deliver every surfaced report the scout emits (ready or pending_input) to Slack as well as the inbox; a report the judge suppressed stays out of Slack by design: an integration_id for the workspace, plus either a channel (channel_id|#channel-name) or up to five users to DM (member_id|@display-name), never both.
A scoped API key or OAuth token needs integration:read and inbox:read (or the matching write scopes) on top of signal_scout:write to set slack; a minimally scoped credential gets a permission error.
thread_reports: true posts a report as a short lead message with the rest split into replies at the summary's section labels, so a long report isn't clipped; it doesn't change how findings post.
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 rather than a chatty one you're still calibrating.
A Slack-delivered scout is also exempt from the ignored-reports auto-pause, since consumption there isn't measurable.
display_name: the name the UI shows for the scout. Leave blank to use the default derived from the skill name; it never changes skill_name, which stays fixed.
The only setting here the nested config on scout-create does not take: set it with a -config-update after creation.
model: pins the model the scout's runs use. Leave unset to follow the fleet default, which is what most scouts should do; set it when a scout's job needs a stronger model (long research) or a cheaper one (a frequent, mechanical probe) and say why in the body.
Early access: on a project not enrolled in the scouts-model-config preview, any non-null value is rejected with "Choosing a scout model is not available on this project yet.", so only recommend pinning where that flag is on.
mcp_gateway_server_ids: MCP store servers (by id) this scout's runs may mount, chosen from the connections members have shared with the whole team.
Empty (the default) mounts none of the shared servers. The intent is that only team-shared connections back a scout run, so runs behave the same whoever edits the scout; where MCP gateway enforcement is not yet active on the project, the launch path may still mount the acting user's personal connections, so check the run's mounted servers in its transcript when that matters.
Treat it like network_access: it hands the scout third-party tools with whatever access the shared connection carries, changes are activity-logged, and the body should name what the scout uses each server for.
repositories — defaults to []: the scout's sandbox holds no checkout, which is right for a scout that only reads the project over MCP.
Set ["organization/repository", ...] for a scout that reasons about code, and its sandbox clones each one before the run starts, so the scout can grep the tree, read the layout, and run the project's own build, type check, and tests instead of fetching files one gh api call at a time.
Up to 10 per scout, and each must be reachable through the project's GitHub connection — an unreachable name is refused on write rather than surfacing as a clone failure mid-run.
The scout's GitHub access stays read-only whether or not it clones, so a listed repository gives it a tree to read and never the ability to push, comment, or open a pull request. Write access for a scout is a separate opt-in that does not exist yet.
A multi-repository scout gets each tree on its default branch; there is no per-repository branch selection.
Each tree carries the repository's full commit history, so a skill body can run git log, git blame, and --since against it without an unshallow fetch first.
Applies from the scout's next run, and changes are activity-logged.
tags — free-form labels grouping the fleet, e.g. ["revenue", "on-call"]. Up to 10 per scout, normalized to lowercase kebab-case (On Call → on-call) and deduped.
Set them at create time: a scout that lands already grouped saves a follow-up edit, and the desktop app's scout list filters on them.
Prefer a tag that already exists on the fleet (-config-list shows every scout's tags) over minting a near-duplicate — revenue and revenue-analytics fragment the same group.
A write replaces the set, so send the full desired list, not just the additions.
Filter the roster with -config-list's tags parameter (comma-separated, matches a scout carrying any of them).
structured_output_schema — defaults to null (channel off).
Set a JSON Schema (draft 2020-12, root "type": "object") describing one structured record and the scout gains a third output channel next to reports: each run is shown the schema and told to submit conforming records via scout-record-output (one per run, or one per judged entity — the skill body decides the cardinality and when to record).
Records are validated server-side against the schema (all-or-nothing per call) and recorded in the project as $scout_structured_output events with scalar payload keys flattened to output_<key> properties — so a judging/scoring scout's series is chartable in insights directly, and past records are queryable like any events (filter on subject or run_id, break down on output_<key>).
The channel also requires emit: a dry-run scout has nowhere to record to, so scout-record-output fails closed for it.
Reach for this when the scout's job is a recurring measurement (judge each sampled report good/bad/unsure with a reason, score accounts, classify sessions) rather than surfacing anomalies; keep enums small and add a free-text reason field so the series is breakdown-friendly and auditable.
The skill body should say what to sample, how to judge, and what subject to stamp on each record; the schema owns the record shape.
Because the records are ordinary events, anything that consumes events can act on one — a workflow or CDP destination triggered on $scout_structured_output, filtered to your skill_name and an output_<key> value, turns a measuring scout into the front half of an automation (route the verdict to a channel, a task, a CRM) with no human in between.
The full design treatment — rubric writing, rates-over-scores record shape, rubric versioning, sampling discipline, the seam with reports, what changes once a grade is a routing decision, and the non-judging variants (structured extraction, state snapshots, synthetic telemetry) — is the recurring measurement / LLM-judge pattern in references/scout-patterns.md.
Steering with notes (no authoring needed)
Sometimes you don't want to change the scout — you want to tell it something.
That's what scout notes are for: short steering messages any team member (or an agent acting for one) leaves for the fleet, which every run picks up as prior context alongside its scratchpad and run history.
Reach for a note instead of an edit when the steer is feedback, a pointer, or context with a shelf life:
- Feedback on output: "the staging traffic spike you keep flagging is known noise, stop reporting it".
- A pointer: "dig into the EU signup funnel this week — we think something regressed".
- Context the scout couldn't know: "we shipped a new checkout on Tuesday, treat conversion shifts after that as expected".
The tools (reads on the public signal_scout:read scope; because scouts read notes verbatim, writing or deleting one requires the same authorization as editing a scout's skill — the llm_skill:write scope plus skill editor access):
posthog:scout-notes-create {"content": "...", "skill_name": "signals-scout-web-analytics"} — address one scout by its exact skill name (roster via scout-config-list; the skill must already exist, so a typo'd target is rejected instead of silently steering no one), or omit skill_name for a general note every scout sees.
Optionally set expires_at so a time-boxed note ("watch closely this week") retires itself.
skill_name: "pipeline:report-research" addresses the report pipeline's research stage instead of any scout, for guidance about how the reports it builds from clustered signals get researched, judged, and routed ("route billing-adjacent reports to the billing folks"). Reports a scout authors directly never pass through that stage, so a rule for them belongs in a fleet-wide note (omit skill_name) or a per-scout one. It is the only pipeline:* audience; any other value is rejected.
posthog:scout-notes-list — browse the active notes; pass skill_name to see what a given scout will read.
Expect system-derived notes alongside the human ones: a dismissal or snooze note, a Discuss question, a thumbs-rating note, and a reviewer add/remove on a report are each forwarded to the relevant scout as a note, labelled by origin (report_dismissal, report_discussion, report_feedback, report_reviewer_correction; a note left directly is human). Derived notes expire on their own after ~30 days.
Three caveats: a Discuss question or rating note only forwards when the person had the notes-write authorization themselves (skill-editor access plus, on a scoped credential, signal_scout:write and llm_skill:write); a reviewer correction only forwards when the person had skill-editor access on the canonical project (the reviewer change itself still lands on the report); and the list hides every derived origin from a caller without report read access (inbox:read), since they quote report content. A missing derived note can mean either. A dismissal note is still on the report and a Discuss question on its discussion task, but a rating note exists only as the forwarded scout note (plus an analytics event), so a rating note that did not forward is gone.
posthog:scout-notes-delete {"id": "..."} — retire a note that's been acted on or no longer applies.
posthog:scout-run-now {"id": <config_id>, "note": "..."}: steer one run only. The note (up to 1,000 characters) is read by that run next to the durable notes and is never delivered to a later run as a note, so use it for "check this now" instead of a note every scheduled run would keep reading. It does stay visible in that run's metadata (run_note) when a later run reads its history, so phrase it as a dated one-off ("today only: ...") rather than standing policy. It needs skill-editor access and, on a scoped credential, llm_skill:write on top of the base signal_scout:write, the same two scopes as a durable note (a 403 otherwise; drop the note to run without it), and spends a run like any manual dispatch.
How scouts treat notes: every run reads its notes in step 1 and is told to let a fresh note visibly shape what it investigates — but notes are advisory.
They direct attention; they don't lower the scout's evidence bar or force a report, so a note saying "report X" still gets an honest investigation, not an automatic emit.
The scout closes the loop in its run summary (which notes it acted on and how) and folds absorbed guidance into its scratchpad.
Choosing between a note and an edit: a note is the right tool for this project, right now steering and for trying a nudge before committing to it; a skill edit is the right tool once the steer is permanent policy (a disqualifier, a threshold, a scope change).
A note that you keep re-leaving is a skill edit waiting to happen — promote it.
Note lifecycle stays with humans: scouts never delete notes, so retire acted-on notes yourself (or set expires_at up front) to keep the channel high-signal.
Workflow-triggered runs
A workflow's "Run scout" step starts a run when an event fires, for example a new GitHub issue or a pull request.
Every run's prompt names how it started in Your run identity: triggered_by is schedule, manual, workflow, or check (experiment on a private trial run).
A workflow run also carries trigger_workflow_id, the id of the workflow that fired.
Branch on that value in the body ("if triggered_by is workflow ...") rather than on whether a note is present.
What the run sees depends on the step's note:
- With a note, the harness makes the subject the note names the run's first job.
The run handles that subject completely before anything else: it investigates, decides, files a report or records why it rejected the subject, and writes the memory the body asks for.
The scout's routine is optional on that run.
If the body says nothing about workflow-triggered runs, the run skips the routine and leaves it to the schedule.
- Without a note, the run is told a workflow started it and that nothing names the event.
It runs the body as it would on a schedule, unless the body says what to do on a workflow-triggered run.
Write a workflow-triggered section in the body when the default is wrong for the scout.
For example, "on a workflow-triggered run, also refresh the label cache", or "on a workflow-triggered run with no note, only check the last hour".
Incremental state needs a full pass.
A run that skipped its routine or cut it short must leave cursors, baselines, and "last swept" markers as they were, and write memory only about the subject it handled.
The harness tells every workflow run with a note this.
Name the scout's own incremental keys in the body, because only the body knows which scratchpad entries a partial pass must not move.
Write the step's note from identifiers.
Use a pull request number, an issue URL, or an alert id, for example Issue #{event.properties.issue_number}.
Do not paste a title, a body, or other free text from the event.
The scout reads the note as untrusted input, and an identifier gives it something to look up with its own tools.
Test loop
Dogfood the scout yourself before you ever spend a real run. You — the agent authoring the scout — have the same Flind MCP tools a scout uses at runtime (execute-sql, read-data-schema, the per-product list tools, scout-project-profile-get).
The cheapest, fastest iteration doesn't touch a scout run at all: walk the scout's own logic against the live project by hand.
Confirm the watched event/entity exists and has the shape you assumed, run the discriminator to check it actually separates signal from noise on this project's data, and run each explore pattern's queries to see what they surface.
This loop is free and instant — refine the body against what you find, re-run the queries, repe
…(truncated)
1---2name: authoring-scouts3description: >4 Write, edit, and adapt Flind Signals scouts: scheduled agents that scan a project5 and report findings. Use to change a canonical scout's scope, thresholds, schedule,6 or dry-run settings; add a scout for an uncovered surface; record structured output7 from scheduled LLM scoring; or give feedback through notes. Covers SKILL.md structure,8 report requirements, follow-up report checks, structured output, duplicate detection,9 scratchpad memory, scout notes, per-team skills-store and canonical repository edits,10 and private prompt trials with saved rubrics. Trigger on11 "write/edit/customize a signals scout", "new scout for X", "tune my scout schedule",12 "make a scout that watches <event>", "score/judge/measure X with a scout",13 "test/compare scout prompts", "generate scout rubrics", "structured output from a scout", "scout output to Slack",14 "leave a note for / give feedback to a scout".15metadata:16 source: https://skillmd.com/skills/thehalfmoon/authoring-scouts17 owner_team: signals18---1920# Authoring Signals scouts2122A **scout** is a scheduled agent that wakes on its own interval, looks at one Flind project, decides what's genuinely worth surfacing, and writes it into the Signals inbox as a **report** — or closes out empty, which is a real outcome.23Flind ships a fleet of **canonical scouts** (a cross-product generalist plus per-surface specialists).24This skill helps you and your agent **adapt those canonical scouts to a specific project**, or **author new scouts from scratch** for a use case the fleet doesn't cover.2526A report-producing scout's output is the **report channel**: it lists `emit_report` / `edit_report` in its frontmatter `allowed_tools` and authors or edits full inbox reports 1:1 directly.27Most of the canonical fleet runs this way, and **every new report-producing scout should too** — include the `allowed_tools` opt-in when you author one.28A scout whose output is a product surface (for example, suggestions on a workflow page) omits both tools; see [Scouts with a product-specific output](references/report-contract.md#scouts-with-a-product-specific-output).29Where that output _lands_ is a separate, per-scout config decision: the report goes to the Signals inbox, and the same report can be delivered to a Slack channel or DM at the same time (`output_destinations` under Run posture) — so don't rule a scout out of a job because the user wants the result in Slack.30(A historical signal-emitting channel — weak `emit-signal` findings a pipeline consolidated — still exists in the harness for scouts that never opted in, but it is deprecated: don't author new scouts on it, and opt an old one in rather than extending it.)3132A scout is an `LLMSkill` that holds a `SignalScoutConfig`.33The harness loads the body **verbatim** as the agent's system prompt, and progressively reads any bundled reference files on demand.34**The config row is what makes a skill a scout.** Any valid skill name works, so the `signals-scout-` prefix is optional.35The prefix controls one thing: the coordinator globs `signals-scout-*` to auto-register a config for a skill that has none.36A skill with any other name needs its config created alongside it, which is what `scout-create` does.3738## The job before the writing3940Don't write a scout in the abstract.41Ground it in the target project first — a scout is only as good as its fit to the data it watches.42(The scout tools were recently renamed from `signals-scout-*` to `scout-*`; if a `scout-*` name comes back unknown, the server may still expose it under the legacy `signals-scout-*` name — search the tool catalog and call whichever name it returns.)43441. **Read the project.** `posthog:scout-project-profile-get` returns the deterministic snapshot the scout itself cold-starts from: products in use, top events with reach/burst metrics, integrations, existing inbox counts.45 If the scout watches a specific event, confirm it exists and check its shape with `posthog:read-data-schema`.46 A scout for an event the project doesn't capture is dead on arrival.472. **See what already runs.** `posthog:scout-config-list` lists every existing scout on the project with its schedule, `enabled`, and `emit` posture, plus each scout's `description` (pulled from the skill's frontmatter) so you can tell what a scout watches without loading its body.48 Don't duplicate a surface a canonical scout already covers — adapt that one instead.493. **Read the closest canonical scout.** It's your template and your reference shape.50 Pull it with `posthog:skill-get {"skill_name": "signals-scout-<x>"}` (per-team rows) or read it from the repo at `products/signals/skills/signals-scout-*/`.51 The generalist (`signals-scout-general`) is the broad template; if your scope is domain-tight, pick the specialist closest to your surface — list the live roster with `posthog:skill-list {"search": "signals-scout"}` (specialists exist for most product surfaces: error tracking, logs, AI observability, experiments, feature flags, session replay, web analytics, surveys, and more).524. **Skim the inbox.** `posthog:inbox-reports-list` shows what reports are actually landing — calibrate so your scout adds signal, not noise.5354## Choose the path5556There are two independent decisions: **what** you're building, and **where** it lives.5758### What5960| Situation | Approach |61| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |62| A canonical scout is close but too broad / too noisy / missing a disqualifier for this project | **Adapt** it — narrow the scope, add disqualifiers, retune thresholds. |63| You want a surface no canonical scout covers (a custom event, a product-specific funnel) | **New scout from scratch** — copy the closest canonical scout as scaffolding, replace the domain discriminator + explore patterns. |64| You want to compare prompts, models, or reasoning efforts before applying a change | **Private trial** — keep the saved scout intact, review its rubric, and compare variants through the Test loop below. |65| You only want to change _when_ / _whether_ a scout runs | **No authoring** — just tune the config (see Run posture). |66| You have one-off feedback, a pointer, or short-lived context for a scout | **No authoring** — leave a note (see Steering with notes). |6768### Where6970| Path | Mechanism | Use when |71| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |72| **Per-team** (the common user path) | Create a new runnable scout via `posthog:scout-create`; edit its prompt or files later via `posthog:skill-update` / `-file-create`, and tune its runtime config via `posthog:scout-config-update`. | Customizing for one project. The harness globs the row in on the next tick; canonical sync leaves your edited ("diverged") row alone. |73| **Canonical** (Flind contributors) | Edit disk under `products/signals/skills/signals-scout-*/`, lint/build, open a PR. | Improving a scout for _every_ enrolled project. `lazy_seed` mirrors it onto all enrolled teams on the next tick. |7475**Adapting-in-place tradeoff:** editing a canonical scout's row for your team marks it **diverged** — you stop receiving upstream improvements to that scout.76If you only need an _additional_ behavior, prefer authoring a **new, differently-named** scout (`signals-scout-<your-scope>`) and leaving the canonical one intact.7778See [`references/lifecycle-and-testing.md`](references/lifecycle-and-testing.md) for the exact skills-store calls, the build/lint commands, and how seeding works.7980## Write the scout8182First pick the **shape**.83[`references/scout-patterns.md`](references/scout-patterns.md) is a cookbook of the reference architectures scouts fall into — anomaly watcher, liveness/absence watcher, zero-result/unmet demand, watchlist explore/exploit, cross-product correlation, recommendation/gap, warehouse-backed source, custom single-event, open-text theme, adversarial/abuse concentration, external-tool/code, state∩code intersection, custom issue-tracker/work-queue, daily digest/roll-up, triage over a pre-detected stream, first-person dogfooding/probe, recurring measurement/LLM-judge, maintainer/steward, owner-scoped book/queue, trigger-to-brief enrichment, dispatcher/campaign, fleet meta-scout/reviewer — each mapped to a canonical scout or a proven custom shape you can copy as scaffolding.84It also makes the key point that **a scout can watch any source Flind ingests into the data warehouse, not just analytics events** (a Slack channel sync, a billing system, a CRM, a support inbox), plus external systems reachable from the sandbox, other agents' output, and the scout fleet itself.85And where a built-in signals source already covers the surface (GitHub and Linear issues), the issue-tracker pattern says where that source stops and a scout starts paying for itself.86A scout does not have to stop at describing a fix: the **maintainer / steward** pattern is how a scout holding `write_scopes` keeps a family of dashboards, alerts, warehouse views, or scanner prompts healthy itself, with a write ladder that says which changes it applies, which it verifies and reports, and which it hands to a human.87Find the closest pattern, then write the body.8889Follow [`references/scout-anatomy.md`](references/scout-anatomy.md) — it has the frontmatter schema (including the `allowed_tools` report-channel opt-in every report-producing scout needs; a scout with a [product-specific output](references/report-contract.md#scouts-with-a-product-specific-output) omits it), the canonical body structure (quick close-out → orient → domain discriminator → explore patterns → save-memory → decide → disqualifiers → close-out), the lean-body rule, and copy-ready skeleton templates for both a specialist and the generalist.9091**Write the body feature-forward.** The body is a prompt a run reads in full, every run, for as long as the scout lives — so it states what the scout watches and how it decides, and nothing else. Four things do not belong in it:9293- **No rollout state.** A preview flag, an early-access gate, a "recently renamed" tool, a port that is happening one scout at a time. It is true this month and misleading next month, and a run cannot tell which. Write the behavior the scout should follow now; if a capability may be absent, say how the run tells, not when it is due.94- **No backlog.** Work that is planned, a field that does not exist yet, a lane somebody means to add. A run cannot act on it, so it only spends tokens and invites the run to wait for something.95- **No project-only facts.** A metric, dashboard, event, id, or reviewer that exists in one project. A canonical scout ships to every project, so a fact from one of them is wrong for almost every run. Text about an optional product says how the run tells whether the project uses it, and never assumes it does.96- **No duplicated harness mechanics.** The report-channel contract, the run gates, and the close-out format come from the harness prompt, which every report-channel scout is given. A copy in the body drifts from the real one and the run then holds two versions of the same rule. Keep the body to your scout's own domain framing.9798The same four apply to a bundled reference: it is read at run time too, so it carries no more rollout state or backlog than the body.99100Two craft references the whole fleet reasons in terms of — a good scout's **Decide** and **memory** sections are built on them, so read them before writing those sections:101102- [`references/report-contract.md`](references/report-contract.md) — the report tools (`scout-emit-report` / `scout-edit-report`), the report bar (author 1:1 only for a finding you'd own end-to-end), `suggested_reviewers` routing, the dedup-via-`report_id` discipline (the channel isn't idempotent — reconcile against existing reports via the vanilla `inbox-reports-list` / `inbox-reports-retrieve` before authoring), and the accepted caveat that the pipeline may later rewrite an authored title/summary.103 This is how your scout decides _what clears the bar_ and _how to file it_.104- [`references/dedupe-and-memory.md`](references/dedupe-and-memory.md) — the four-states classifier (net-new / material-update / already-covered / addressed-or-noise), the scratchpad key-prefix vocabulary, and the cross-project noise patterns.105 This is how your scout avoids re-filing and learns across runs.106- [`references/report-checks.md`](references/report-checks.md) — the follow-up checks a scout attaches to a report so "did the fix hold?" is measured later instead of remembered.107 This is how your scout closes the loop on a finding after somebody acts on it.108109A report is backward-looking; a **check** is the opposite direction — an expectation plus a time to test it, written onto a report with `scout-report-check-create`.110Give your scout a checks section when its findings are the kind whose fix shows up in data later.111Three rules belong in the body, and the reference has the rest:112113- **List the report's existing checks first** (`scout-report-check-list`), every time. An open check for the same claim makes a second one noise, and a report holds at most five open checks.114- **`metric_threshold` wherever one number settles the claim and an event or action series can carry it.** The coordinator measures it itself, with no scout run.115- **`agent` when no single number settles it, or when the number lives outside events** — a log rate, a fix whose effect shows in which entities fire rather than how many, a claim that needs a stack trace read.116117The single most important design decision in any scout is its **signal-vs-noise discriminator** — the cheap profile-shape read that separates "worth investigating" from "baseline".118For error tracking it's the `count` vs `distinct_users` ratio; for CSP it's reach over raw count.119Your new scout needs its own.120Name it explicitly near the top of the body so every run anchors on it.121122(The one exception: a **measurement scout** on the structured-output channel holds no bar — it applies a **rubric** to every sampled item, and the rubric takes the discriminator's slot as the design surface to name, dogfood, and calibrate. See the recurring measurement / LLM-judge pattern in `references/scout-patterns.md`.)123124A second design consideration applies to a **metric-shaped scout** — one that scores, ranks, or reports a named, reusable measure, whether a business measure (MRR, churn risk, usage revenue, activation) or operational telemetry it computes every run to monitor or report (cost per run, failure or error rates, latency, throughput).125If the project has an approved metric for that measure (`metric-list` shows what exists), name it in the body and run it with `data-catalog-metric-run`, so the scout's number matches the one the team already reports.126127## Run posture (config)128129A scout's schedule and emit behavior live on its `SignalScoutConfig`, separate from the skill body.130For a **brand-new scout**, pass these settings in the nested `config` object of the `posthog:scout-create` call, including creating it disabled or in dry-run **before it ever runs**.131When creating a scout to test an idea, set `config.enabled=false` so scheduled runs cannot interfere with the trial.132The endpoint creates the skill and config atomically, always opts the scout into the report channel, and safely re-applies config fields when the same definition is retried.133A scout with a product-specific output must stay off the report channel, so create it with `skill-create` and `scout-config-create` instead; see [Scouts with a product-specific output](references/report-contract.md#scouts-with-a-product-specific-output).134Otherwise the coordinator auto-registers an enabled config on the default every-24-hours schedule on its next tick (up to ~30 min).135For an **existing scout**, tune with `posthog:scout-config-update` (find the `id` via `-config-list`):136137- `run_interval_minutes` — 30 to 43200.138 Default 1440 (every 24 hours).139 Slow a chatty or expensive scout by raising this.140- `run_cron_schedule`: a five-field cron expression (`'30 9 * * *'`, `'0 9 * * 1-5'`) evaluated in the project's timezone; occurrences must be at least 30 minutes apart.141 When set it takes precedence over `run_interval_minutes`, so a "slow it down" edit on a cron scout has to change or clear the cron (set `null` to return to the rolling interval).142 A new or edited schedule anchors on the edit time and waits for its next slot rather than catching up on a past one.143 Reach for it when the run should land at a wall-clock time: a digest before standup, a weekday-only watch.144- A scheduled run starts inside a window, not at an exact minute.145 Each scout has a fixed offset in that window, so its cadence does not change from run to run.146 A cron scout starts within 20 minutes of its cron time, so a `0 9 * * *` scout starts at the same minute between 9:00 and 9:20 every day.147 An interval scout starts within the same 30-minute coordinator tick, and `last_run_at` records the tick, not the start.148 A scout's first run, a manual run, a workflow run, and a report-check run start at once.149 When you explain or write a schedule, describe the time as a window.150- `enabled` — `false` pauses the scout entirely (coordinator skips it).151- `precheck_query` — defaults to null: a HogQL `SELECT` that a scheduled run evaluates before it starts, with `{since}`, `{now}`, and `{interval_minutes}` placeholders.152 No rows, or one row with one false value (such as a zero `count()`), skips the run before it creates a run row or a sandbox. Any other result starts the run, and the rows enter the run prompt. A query error also starts the run.153 Only scheduled runs evaluate it: a manual, workflow, or report-check run always starts.154 Set it for a scout that has nothing to do on most ticks. Test the query with `posthog:scout-config-precheck-test` before you save it, because a scheduled check runs as the scout's acting user and the dry run runs as you.155 A canonical scout can ship a default in its `scout-precheck-query` frontmatter. `precheck_query` overrides that default, null restores it, and `precheck_disabled: true` turns off both.156 The full recipe, the placeholder semantics, and how to diagnose a tick with no run row are in [`references/scheduled-precheck.md`](references/scheduled-precheck.md).157- `emit` — defaults to **`true`**: the scout writes its reports straight to the inbox.158 Set **`emit=false` (dry-run)** to inspect an ordinary run's reasoning without publishing reports to the inbox.159 Private trials capture reports and memory separately and work while the source scout is paused or has `emit=false`.160- `network_access` — defaults to **`trusted`**: the scout's sandbox can only reach the platform's trusted-domain allowlist (Flind, GitHub, common package registries), which covers the MCP loop and `gh` but blocks everything else.161 Set **`full`** for a scout whose skill needs to read arbitrary external sites, e.g. documentation, papers on arxiv.org, or a vendor status page.162 Applies from the scout's next run, and changes are activity-logged.163- `auto_pause_exempt` — defaults to `false`.164 A scout whose reports nobody engages with (no open, rating, or action — the cloud web inbox records reads; other clients don't yet) is warned and then paused automatically (`pause_reason=ignored`) — every run costs a sandbox agent, so a scout producing output no human consumes shouldn't keep running forever. A scout that is merely quiet is only flagged (`pause_reason=no_output`, a warning that never advances to a pause), since a watch scout's silence can be its job.165 `-config-list` shows the warning as `status=pending_pause` and the pause as `status=paused_by_system`; setting `enabled=true` again resumes the scout with a fresh grace window before the sweep may judge it again.166 Set `auto_pause_exempt=true` up front for a watchdog scout whose whole job is to stay quiet, so it never even picks up the quiet flag.167- `write_scopes` — defaults to `["notebook:write"]`: the scout reads the project and writes its findings, its memory, and notebooks.168 `notebook:write` reaches every notebook in the project, not only the ones the scout made. Send `[]` (or drop it from the list) for a scout that should write nothing but its findings and memory. Unlike the other scopes, a run keeps it when its author no longer resolves and it acts as another project member.169 Grant `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`, or `experiment:write` to a scout whose job is to **maintain** one of those things rather than only describe what it would change.170 The body of such a scout follows the maintainer / steward pattern in `references/scout-patterns.md`: a curated inventory, a write ladder (do-and-log, do-verify-report, hand-to-a-human), a per-run change cap, and a rolling maintenance report naming every object changed.171 Each scope is project-wide and covers update and delete of every object of its kind, not only the ones the scout made, so grant only what the scout's body actually tends, and say in the body what it may change and when.172 `llm_skill:write` is the one to think twice about: custom scouts are skills in the same store, so a scout holding it can edit a sibling scout's body, or the body it runs from itself. Grant it to a scout whose job really is tending a set of skills, name that set in the body, and say there that the scouts are off limits unless tending them is the job.173 `warehouse_view:write` and `warehouse_table:write` are separate on purpose: a scout that keeps a set of views healthy does not also need to create tables. Take both rows only when the scout tends both.174 `replay_scanner:write` permits scanner maintenance. A scout must set a `credit_limit` when it creates, copies, or enables a scanner, and before it changes targeting, sampling, or the model of an enabled scanner. It cannot clear a limit, delete a scanner, or start manual scans, retries, or backfills. Use `enabled: false` to stop a scanner and keep its observations. Change a shared rating only to record an explicit user verdict, because ratings steer how the scanner judges later sessions.175 `customer_task:write` covers every Customer analytics task in the project, including tasks assigned to other people: create, update (status, due date, assignee), archive, and restore archived tasks, with no delete. Say in the body whose tasks the scout tends, and whether it may reassign one.176 Customer analytics tasks are still behind the `customer-analytics-customer-tasks` feature flag. On a project without it the task tools do not exist and the grant does nothing, so do not grant it there.177 `canvas:write` reaches every canvas in a public space and every canvas the acting user created: publish, layout, runtime state, and soft-delete of the acting user's own canvases. A scout run cannot create a canvas, because a scout task has no space to file one in. Create the canvas first, name its id in the body, and follow the one-canvas maintainer variant in `references/scout-patterns.md`. Each published version records the run's task, so version history shows which run published it.178 `experiment:write` is the one grant that changes what end users see. It reaches every experiment in the project: create, edit, duplicate, archive, launch, pause, resume, end, and reset. Launch and pause turn the linked feature flag on and off. A scout cannot delete an experiment, copy one to another project, migrate a legacy one, or open a flag cleanup pull request. Without `feature_flag:write`, which no scout can hold yet, it also cannot ship a variant or change the variants, rollout, or holdout once an experiment has launched or its flag is on. So a scout sets up drafts and ends experiments, and a person ships them. Say in the body which experiments the scout tends, and which lifecycle changes it may make without a person asking.179 Only the person the scout's runs act as (whoever authored it) or a project admin can set the field, and grants are activity-logged. A scoped API key must itself carry each scope it grants.180 A granted scout is told in its run prompt which objects it may change, and is asked to name every change in its close-out. The grant is an upper bound: the acting user's own permissions still apply to each object, and the scout reports a refused write rather than retrying it.181 A dry run (`emit: false`) never holds the grant, so a scout can be previewed without it changing anything.182 To audit the writes after a run, see "Auditing what a scout changed" in `working-with-scouts`: the changes land in the activity log under the scout's acting user, tagged "via MCP", with no scout or run name on the row.183 Applies from the scout's next run.184- `output_destinations` — defaults to none.185 When adding Slack to an existing scout, first read `output_destinations`, then send the full object with every key preserved. Updates replace the object, so sending only `slack` removes an existing `webhook` pointer.186 Set `slack` to deliver every surfaced report the scout emits (`ready` or `pending_input`) to Slack as well as the inbox; a report the judge suppressed stays out of Slack by design: an `integration_id` for the workspace, plus either a `channel` (`channel_id|#channel-name`) or up to five `users` to DM (`member_id|@display-name`), never both.187 A scoped API key or OAuth token needs `integration:read` and `inbox:read` (or the matching write scopes) on top of `signal_scout:write` to set `slack`; a minimally scoped credential gets a permission error.188 `thread_reports: true` posts a report as a short lead message with the rest split into replies at the summary's section labels, so a long report isn't clipped; it doesn't change how findings post.189 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 rather than a chatty one you're still calibrating.190 A Slack-delivered scout is also exempt from the ignored-reports auto-pause, since consumption there isn't measurable.191- `display_name`: the name the UI shows for the scout. Leave blank to use the default derived from the skill name; it never changes `skill_name`, which stays fixed.192 The only setting here the nested `config` on `scout-create` does not take: set it with a `-config-update` after creation.193- `model`: pins the model the scout's runs use. Leave unset to follow the fleet default, which is what most scouts should do; set it when a scout's job needs a stronger model (long research) or a cheaper one (a frequent, mechanical probe) and say why in the body.194 Early access: on a project not enrolled in the `scouts-model-config` preview, any non-null value is rejected with "Choosing a scout model is not available on this project yet.", so only recommend pinning where that flag is on.195- `mcp_gateway_server_ids`: MCP store servers (by id) this scout's runs may mount, chosen from the connections members have shared with the whole team.196 Empty (the default) mounts none of the shared servers. The intent is that only team-shared connections back a scout run, so runs behave the same whoever edits the scout; where MCP gateway enforcement is not yet active on the project, the launch path may still mount the acting user's personal connections, so check the run's mounted servers in its transcript when that matters.197 Treat it like `network_access`: it hands the scout third-party tools with whatever access the shared connection carries, changes are activity-logged, and the body should name what the scout uses each server for.198- `repositories` — defaults to `[]`: the scout's sandbox holds no checkout, which is right for a scout that only reads the project over MCP.199 Set `["organization/repository", ...]` for a scout that reasons about code, and its sandbox clones each one before the run starts, so the scout can grep the tree, read the layout, and run the project's own build, type check, and tests instead of fetching files one `gh api` call at a time.200 Up to 10 per scout, and each must be reachable through the project's GitHub connection — an unreachable name is refused on write rather than surfacing as a clone failure mid-run.201 The scout's GitHub access stays read-only whether or not it clones, so a listed repository gives it a tree to read and never the ability to push, comment, or open a pull request. Write access for a scout is a separate opt-in that does not exist yet.202 A multi-repository scout gets each tree on its default branch; there is no per-repository branch selection.203 Each tree carries the repository's full commit history, so a skill body can run `git log`, `git blame`, and `--since` against it without an unshallow fetch first.204 Applies from the scout's next run, and changes are activity-logged.205- `tags` — free-form labels grouping the fleet, e.g. `["revenue", "on-call"]`. Up to 10 per scout, normalized to lowercase kebab-case (`On Call` → `on-call`) and deduped.206 Set them at create time: a scout that lands already grouped saves a follow-up edit, and the desktop app's scout list filters on them.207 Prefer a tag that already exists on the fleet (`-config-list` shows every scout's tags) over minting a near-duplicate — `revenue` and `revenue-analytics` fragment the same group.208 A write **replaces** the set, so send the full desired list, not just the additions.209 Filter the roster with `-config-list`'s `tags` parameter (comma-separated, matches a scout carrying **any** of them).210- `structured_output_schema` — defaults to null (channel off).211 Set a JSON Schema (draft 2020-12, root `"type": "object"`) describing **one** structured record and the scout gains a third output channel next to reports: each run is shown the schema and told to submit conforming records via `scout-record-output` (one per run, or one per judged entity — the skill body decides the cardinality and when to record).212 Records are validated server-side against the schema (all-or-nothing per call) and recorded in the project as `$scout_structured_output` events with scalar payload keys flattened to `output_<key>` properties — so a judging/scoring scout's series is chartable in insights directly, and past records are queryable like any events (filter on `subject` or `run_id`, break down on `output_<key>`).213 The channel also requires `emit`: a dry-run scout has nowhere to record to, so `scout-record-output` fails closed for it.214 Reach for this when the scout's job is a recurring **measurement** (judge each sampled report good/bad/unsure with a reason, score accounts, classify sessions) rather than surfacing anomalies; keep enums small and add a free-text reason field so the series is breakdown-friendly _and_ auditable.215 The skill body should say what to sample, how to judge, and what `subject` to stamp on each record; the schema owns the record shape.216 Because the records are ordinary events, anything that consumes events can **act** on one — a workflow or CDP destination triggered on `$scout_structured_output`, filtered to your `skill_name` and an `output_<key>` value, turns a measuring scout into the front half of an automation (route the verdict to a channel, a task, a CRM) with no human in between.217 The full design treatment — rubric writing, rates-over-scores record shape, rubric versioning, sampling discipline, the seam with reports, what changes once a grade is a routing decision, and the non-judging variants (structured extraction, state snapshots, synthetic telemetry) — is the **recurring measurement / LLM-judge** pattern in [`references/scout-patterns.md`](references/scout-patterns.md).218219## Steering with notes (no authoring needed)220221Sometimes you don't want to change the scout — you want to _tell it something_.222That's what **scout notes** are for: short steering messages any team member (or an agent acting for one) leaves for the fleet, which every run picks up as prior context alongside its scratchpad and run history.223Reach for a note instead of an edit when the steer is feedback, a pointer, or context with a shelf life:224225- Feedback on output: "the staging traffic spike you keep flagging is known noise, stop reporting it".226- A pointer: "dig into the EU signup funnel this week — we think something regressed".227- Context the scout couldn't know: "we shipped a new checkout on Tuesday, treat conversion shifts after that as expected".228229The tools (reads on the public `signal_scout:read` scope; because scouts read notes verbatim, writing or deleting one requires the same authorization as editing a scout's skill — the `llm_skill:write` scope plus skill editor access):230231- `posthog:scout-notes-create {"content": "...", "skill_name": "signals-scout-web-analytics"}` — address one scout by its exact skill name (roster via `scout-config-list`; the skill must already exist, so a typo'd target is rejected instead of silently steering no one), or omit `skill_name` for a general note every scout sees.232 Optionally set `expires_at` so a time-boxed note ("watch closely this week") retires itself.233 `skill_name: "pipeline:report-research"` addresses the report pipeline's research stage instead of any scout, for guidance about how the reports it builds from clustered signals get researched, judged, and routed ("route billing-adjacent reports to the billing folks"). Reports a scout authors directly never pass through that stage, so a rule for them belongs in a fleet-wide note (omit `skill_name`) or a per-scout one. It is the only `pipeline:*` audience; any other value is rejected.234- `posthog:scout-notes-list` — browse the active notes; pass `skill_name` to see what a given scout will read.235 Expect system-derived notes alongside the human ones: a dismissal or snooze note, a Discuss question, a thumbs-rating note, and a reviewer add/remove on a report are each forwarded to the relevant scout as a note, labelled by `origin` (`report_dismissal`, `report_discussion`, `report_feedback`, `report_reviewer_correction`; a note left directly is `human`). Derived notes expire on their own after ~30 days.236 Three caveats: a Discuss question or rating note only forwards when the person had the notes-write authorization themselves (skill-editor access plus, on a scoped credential, `signal_scout:write` and `llm_skill:write`); a reviewer correction only forwards when the person had skill-editor access on the canonical project (the reviewer change itself still lands on the report); and the list hides every derived origin from a caller without report read access (`inbox:read`), since they quote report content. A missing derived note can mean either. A dismissal note is still on the report and a Discuss question on its discussion task, but a rating note exists only as the forwarded scout note (plus an analytics event), so a rating note that did not forward is gone.237- `posthog:scout-notes-delete {"id": "..."}` — retire a note that's been acted on or no longer applies.238- `posthog:scout-run-now {"id": <config_id>, "note": "..."}`: steer one run only. The note (up to 1,000 characters) is read by that run next to the durable notes and is never delivered to a later run as a note, so use it for "check this now" instead of a note every scheduled run would keep reading. It does stay visible in that run's metadata (`run_note`) when a later run reads its history, so phrase it as a dated one-off ("today only: ...") rather than standing policy. It needs skill-editor access and, on a scoped credential, `llm_skill:write` on top of the base `signal_scout:write`, the same two scopes as a durable note (a 403 otherwise; drop the note to run without it), and spends a run like any manual dispatch.239240How scouts treat notes: every run reads its notes in step 1 and is told to let a fresh note visibly shape what it investigates — but notes are **advisory**.241They direct attention; they don't lower the scout's evidence bar or force a report, so a note saying "report X" still gets an honest investigation, not an automatic emit.242The scout closes the loop in its run summary (which notes it acted on and how) and folds absorbed guidance into its scratchpad.243244Choosing between a note and an edit: a note is the right tool for _this project, right now_ steering and for trying a nudge before committing to it; a skill edit is the right tool once the steer is permanent policy (a disqualifier, a threshold, a scope change).245A note that you keep re-leaving is a skill edit waiting to happen — promote it.246Note lifecycle stays with humans: scouts never delete notes, so retire acted-on notes yourself (or set `expires_at` up front) to keep the channel high-signal.247248## Workflow-triggered runs249250A workflow's "Run scout" step starts a run when an event fires, for example a new GitHub issue or a pull request.251Every run's prompt names how it started in _Your run identity_: `triggered_by` is `schedule`, `manual`, `workflow`, or `check` (`experiment` on a private trial run).252A workflow run also carries `trigger_workflow_id`, the id of the workflow that fired.253Branch on that value in the body ("if `triggered_by` is `workflow` ...") rather than on whether a note is present.254255What the run sees depends on the step's note:256257- **With a note**, the harness makes the subject the note names the run's first job.258 The run handles that subject completely before anything else: it investigates, decides, files a report or records why it rejected the subject, and writes the memory the body asks for.259 The scout's routine is optional on that run.260 If the body says nothing about workflow-triggered runs, the run skips the routine and leaves it to the schedule.261- **Without a note**, the run is told a workflow started it and that nothing names the event.262 It runs the body as it would on a schedule, unless the body says what to do on a workflow-triggered run.263264Write a workflow-triggered section in the body when the default is wrong for the scout.265For example, "on a workflow-triggered run, also refresh the label cache", or "on a workflow-triggered run with no note, only check the last hour".266267**Incremental state needs a full pass.**268A run that skipped its routine or cut it short must leave cursors, baselines, and "last swept" markers as they were, and write memory only about the subject it handled.269The harness tells every workflow run with a note this.270Name the scout's own incremental keys in the body, because only the body knows which scratchpad entries a partial pass must not move.271272**Write the step's note from identifiers.**273Use a pull request number, an issue URL, or an alert id, for example `Issue #{event.properties.issue_number}`.274Do not paste a title, a body, or other free text from the event.275The scout reads the note as untrusted input, and an identifier gives it something to look up with its own tools.276277## Test loop278279**Dogfood the scout yourself before you ever spend a real run.** You — the agent authoring the scout — have the same Flind MCP tools a scout uses at runtime (`execute-sql`, `read-data-schema`, the per-product list tools, `scout-project-profile-get`).280The cheapest, fastest iteration doesn't touch a scout run at all: walk the scout's own logic against the live project by hand.281Confirm the watched event/entity exists and has the shape you assumed, run the **discriminator** to check it actually separates signal from noise on _this_ project's data, and run each **explore pattern**'s queries to see what they surface.282This loop is free and instant — refine the body against what you find, re-run the queries, repe283284…(truncated)