references/scout-patterns.md · 144000
problem.
- Sibling seams and dedupe prefixes — when a narrow scout deliberately overlaps a canonical one's territory (a per-provider error watcher inside error tracking's domain, a digest over a surface an anomaly scout owns), state the seam in the body in both directions ("defers X to
signals-scout-<y>") and give the scout its own dedupe key prefix so the two never collide on keys or double-file the same entity. Your body carries the ownership map only; the shared discipline is already in the harness prompt (check the fleet before investigating, search the scratchpad by entity rather than by your own prefix, and author anyway when your angle is materially new — citing the sibling's report id). So don't spend body lines re-teaching "check what siblings found" or "don't duplicate": name what's yours and what isn't, and let the prompt handle the rest. - Run-budget discipline — the sandbox kills a run after a fixed budget, so an expensive scout should name its budget at the top of the body and query economically: one combined SQL returning several metrics beats several queries, cap tool calls and items per run, and prefer a fast shallower pass that completes over a thorough one that times out and posts nothing.
- Notebook write-up behind a rich finding. When a finding carries real analysis (charts, a multi-step investigation, several supporting queries), write it up in a notebook with
notebooks-createand link the URL from the finding description, rather than cramming everything into the report prose. The inbox entry stays scannable; the depth is one click away. A case-study scout (one report a day traced from first signal to human reaction) should set itself a depth floor (a fixed section list, a timeline table, a minimum number of executed query cells) so the notebook is a write-up and not a stub. - Parameterize by an operator profile. When several people want the same scout for their own slice (their book, their repositories, their channel), do not clone and edit.
Keep an operator profile section at the top of the body (who, which scope source, timezone, weights, standing exclusions), tell forks to swap that section and set the delivery destination on their own config (
output_destinations, which the body cannot set), and put the shared logic in a companion skill every copy reads at run time withskill-get/skill-file-get. A reference bundled in the scout is copied into each fork's own skill row and read only by that fork, so a fix there reaches one copy; a companion skill is read live and reaches all of them. The third hand-rolled copy on a project is the signal to extract a template. - Shadow an existing job before replacing it. When a scout is meant to take over work a human or an automation already does (a daily failure triage, a hand-written digest), run it in parallel first: same inputs, its own output routed to a DM or a dry run, tagged
shadow, compared against the incumbent for a few cycles. The comparison is the calibration data, and the incumbent keeps running until the shadow has earned the job. - Consolidate per-entity scouts into one family scout. A scout per scanner, per dashboard, per account, or per alert multiplies runs, files a report each whether or not anything happened, and gets auto-paused for being ignored one at a time. One scout per object family with a watch lane over all of them and a maintain lane for the family (see the steward pattern) costs one run, files only on change, and holds the family's shared context in one place.
- Region and mirror awareness. A project that sees more than one region's data (mirrors synced into the warehouse, a
regioncolumn) should split every fleet-level number by region before judging it, because a deploy or provider issue in one region reads as a fleet-wide half-move.
Picking and combining
Start from the table at the top: find the row that matches where your signal lives and what shape it takes, copy that canonical scout, and swap in your discriminator. Real scouts routinely combine patterns — a warehouse-backed scout that does open-text theme aggregation on a fast-sweep/deep-pass cadence is three of these at once, and that's normal. A steward is an anomaly watcher, a recommendation scout, and a maintainer in one body; a book scout is a curated watchlist over one person's accounts with a living report on top. The patterns are starting shapes, not boxes.
Two questions settle most of the choice. Who consumes the output? A team surface wants a digest or a specialist; one person wants an owner-scoped scout and a DM; nobody, because the output is a metric, wants the measurement channel; the object itself, because the fix is the point, wants a steward or a dispatcher. Does detection already exist? If a detector, a health check, a classifier, or a sibling scout already finds the thing, write the judgment layer (triage, reviewer, dispatcher, judge-of-a-judge) rather than a second detector.