references/report-contract.md
The report channel: emit_report / edit_report
A report-producing scout's output is the report channel: it does its research, then authors (or edits) a full inbox SignalReport directly, 1:1.
This reference is the contract for that channel: the tools, their fields, when to author vs. edit, and the two behaviors to design around (it isn't idempotent, and the pipeline may later rewrite what you authored).
The channel is granted via the skill's frontmatter allowed_tools: every report-producing scout lists both emit_report and edit_report there; see Granting the tools.
A scout with a product-specific output omits both tools. See Scouts with a product-specific output.
Tool names vs. opt-in strings. The callable MCP tools are
scout-emit-reportandscout-edit-report— those are the names you invoke. The bareemit_report/edit_report(underscored) used throughout this doc and below are the opt-in strings you list underallowed_tools; they are not callable tool names. And like everyscout-*tool, both report tools require the currentrun_id(the run you're executing in) on every call — omitting it fails validation.
Contents
- Author vs. edit
emit_report— author a full report- Choosing
suggested_reviewers— how a report gets assigned to a human edit_report— update an existing report- Finding "the report I made last time"
- Dedup: the retry is covered, the near-duplicate is not
- The pipeline may rewrite what you authored (accepted)
- Granting the tools
Author vs. edit
| You have… | Use |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| A finished, well-formed finding no existing report covers — file it 1:1 with full control of title/summary. | emit_report |
| New information about a report that already exists (one you authored last run, or a pipeline report). | edit_report |
| An observation you can't yet stand behind as a standalone report. | Neither — write a scratchpad entry and keep investigating (see dedupe-and-memory.md). |
The report bar is high: author only when you'd stand behind the report as a standalone inbox item a human will act on. A weak or partial observation belongs in the scratchpad, where a future run (with more evidence) can pick it up — not in the inbox.
emit_report — author a full report
Judges the report for safety, then persists it at the judged status.
| Field | Type | Notes |
| --------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| run_id | string, required | The current run's id — the run you're executing in, same as every scout-* tool. |
| title | string, required, ≤300, non-empty | The inbox headline. One specific, quantified line. |
| summary | string, required | The report body prose — one tight passage a busy human can act on: a quantified hook (what's happening, with numbers), the pattern that makes it signal rather than noise, the suspected-cause hypothesis, and the recommendation. Cite entities inline as markdown links so the reader pivots straight to source (see below). |
| evidence | list, required, 1–50 | Each {description, source_id}. Becomes a bound signal row backing the report. source_id is the citable entity id. Hard cap of 50 — summarize/trim before calling; a longer list fails validation before the report is judged or persisted. |
| actionability_explanation | string, required | One sentence justifying the actionability call below. |
| actionability | enum, required | immediately_actionable / requires_human_input / not_actionable. You make this call — the channel does not re-research it. See Choosing actionability below. |
| already_addressed | bool, default false | Set when the underlying issue is already handled and you're filing for the record. |
| metrics | list, ≤6, optional | Typed impact measurements the inbox shows as tiles. The report's full set. Each {metric_id, title, kind, query, role?, value?, value_at?, series?, value_format?, unit?, caption?}. See Measuring impact below. |
| charts | list, ≤20, optional | Queries the inbox draws on the report — the report's full set, replacing any it already had. Each {chart_id, title, query, caption?, size?}. See Attaching charts below. |
| suggested_prompts | list, ≤3, optional | Follow-up prompts the inbox offers above the report's Ask AI box (questions to ask, or next-step actions to request), each ≤200 characters and all distinct. See Suggesting follow-up prompts below. |
Cite each entity as a link, not a bare id. In summary and in evidence descriptions, write
the entity you name as a markdown link: reuse the url the returning tool attached (_posthogUrl
and friends), else build one with generate-app-url, and keep the bare id when neither reaches
the entity itself. Two spots stay plain text, because the inbox renders them as text: title, and
the summary's first line, which the inbox lifts out as the card headline. The harness prompt
(Linking what you reference) carries the full rule.
Section labels are where a Slack thread splits. A destination with "Post reports as a thread" on posts a short lead in the channel and each later section as a reply.
A heading (## Evidence) and a bold label on a line of its own (**Evidence**) both mark a section, so write the outline you want the reader to get and either form works.
Leave a blank line above each label, since a label the line above runs onto is part of that paragraph rather than a new section.
Status is decided for you, from safety × actionability:
| Safety judge | actionability | Resulting status | Surfaces in inbox? |
| ------------ | ------------------------ | ---------------- | ------------------ |
| safe | immediately_actionable | READY | yes |
| safe | requires_human_input | PENDING_INPUT | yes |
| safe | not_actionable | SUPPRESSED | no |
| unsafe | (any) | SUPPRESSED | no |
Choosing actionability. The harness prompt carries the full criteria; the call comes down to what a person would have to supply.
immediately_actionable— a coding agent could take concrete, useful action right now: a bug fix, an experiment reaction, a flag cleanup, a UX fix, or a deep investigation with a clear jumping-off point. An unknown root cause does not disqualify a report. When you name the evidence, the code surface, or a failure path someone can reproduce, the investigation is the action.requires_human_input— a code change is plausible, but a person must first make a call only a person can make: a product decision, a trade-off between valid approaches, business context that is not in the data or the code. Name that decision inactionability_explanation. If you cannot name it, the report is not waiting on a human.not_actionable— no answer would lead to code work.
In doubt between the first two, pick immediately_actionable; in doubt between the last two, pick not_actionable.
It is not a free hedge: autostart only considers an immediately-actionable report, so parking one costs it the draft PR a person then has to start by hand.
The result tells you what happened: report_id (always set when a report was persisted — even when suppressed, so you can edit or dedup against it), report_status (the birth status — ready / pending_input / suppressed — the field is named report_status in the response, not status), emitted (true only when it actually surfaced — READY / PENDING_INPUT), safety_explanation, and skipped_reason (set only when a preflight gate stopped the call before any report was created — the AI-data-processing / source-enabled gates that govern every scout write).
Measuring impact
metrics carries the typed measurements that tell a reader what the observation changes, and how many people it reaches.
A consumer draws each one as a tile: the figure with its unit, the title, the window the query covers, and a small trend strip.
Use one primary metric for the key observation, and supporting metrics for the facts around it.
The Inbox shows live metrics on report rows and in report detail when signals-report-metrics is enabled.
The server checks this organization-level flag on each scout write that supplies a non-empty metric list.
The flag is independent of signals-report-charts.
When the flag is off or its check fails:
emit_report(metrics=[...])stores the report without the supplied metrics.edit_report(metrics=[...])ignores the supplied metrics and preserves the report's existing set.edit_report(metrics=[])still clears the set. Omittingmetricspreserves it.
The server drops gated metrics before the safety judge.
Keep the report useful without metrics, and do not retry a write to bypass the flag.
Local development with DEBUG=True enables the metric write path without a flag check.
Omit a metric you cannot measure honestly. A weak number is worse than none. One support ticket and a single migration crash tell the reader nothing. Nor does a rate over a handful of attempts, or a count with no person context.
| Field | Type | Notes |
| -------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| metric_id | string, required | Your own slug (lowercase letters, numbers, _, -, starting with a letter or number), ≤100 characters. Unique within the report, and the key a later edit updates it under. |
| title | string, required | What was observed, and for whom, in one line: Users who hit "Not found" opening a shared chat link, not a label such as Users affected. ≤200 characters. |
| kind | enum, required | What the value measures. See Choosing the kind below. |
| query | object, required | The bounded live query behind the figure. See Keeping the query live and bounded below. |
| role | enum, default | primary for the report's key observation, else supporting (the default). At most one primary per report. |
| value | number, optional | A snapshot you measured in this run. Optional cached fallback only. Pair it with value_at. |
| value_at | timestamp, optional | When you measured value. ISO-8601 with a timezone, and not in the future. |
| series | list, optional | Trailing per-bucket values from the same run, oldest first, ≤14 points. Part of the snapshot, so it needs value and value_at. |
| value_format | enum, default | How to print the figure: count, percentage, percentage_scaled, duration, currency, or number (the default). |
| unit | string, optional | Short suffix that completes the figure, ≤40 characters. See Keeping semantics separate from formatting below. |
| caption | string, optional | Only what the tile cannot show, ≤500 characters. See below. |
| comparison | object, optional | Legacy. Leave it unset. |
A primary affected-users metric and a supporting rate, as they arrive in metrics:
[
{
"metric_id": "people-hitting-not-found",
"title": "Users who hit \"Not found\" opening a shared chat link",
"kind": "affected_users",
"role": "primary",
"value": 412,
"value_at": "2026-06-18T09:00:00Z",
"value_format": "count",
"unit": "users",
"series": [38, 41, 55, 60, 49, 52, 58, 61, 57, 63, 66, 71, 68, 74],
"query": {
"kind": "InsightVizNode",
"source": {
"kind": "TrendsQuery",
"dateRange": { "date_from": "-13d" },
"interval": "day",
"series": [
{
"kind": "EventsNode",
"event": "shared_link_failed",
"math": "dau",
"properties": [{ "type": "event", "key": "reason", "operator": "exact", "value": ["not_found"] }]
}
]
}
}
},
{
"metric_id": "shared-link-failure-rate",
"title": "Shared chat links that fail to open",
"kind": "error_rate",
"value_format": "percentage_scaled",
"unit": "failure",
"caption": "Production traffic only.",
"query": {
"kind": "InsightVizNode",
"source": {
"kind": "TrendsQuery",
"dateRange": { "date_from": "-13d" },
"interval": "day",
"series": [
{
"kind": "EventsNode",
"event": "shared_link_opened",
"math": "total",
"properties": [{ "type": "event", "key": "environment", "operator": "exact", "value": ["production"] }]
},
{
"kind": "EventsNode",
"event": "shared_link_failed",
"math": "total",
"properties": [{ "type": "event", "key": "environment", "operator": "exact", "value": ["production"] }]
}
],
"trendsFilter": { "formula": "B / A", "aggregationAxisFormat": "percentage_scaled" }
}
}
}
]
Choosing the kind
Choose by what the reader will ask, not by what the source makes easy.
| Kind | Use it for | Query shape |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| affected_users | Anything a person experiences: a captured exception with person context, a dead click, a rage click, a failed request on a surface, a broken URL. | Exactly one series, math: "dau". value_format: "count". |
| affected_sessions | A source that establishes sessions but not people. | Exactly one series, math: "unique_session". value_format: "count". |
| occurrences | Noise, and backend failures: a report asking the team to stop reporting something as an error, a Temporal, Celery, or job exception with no person on the event, or a volume counter such as tool calls per week. | Total count. value_format: "count". |
| error_rate | A flow that fails. | Two series plus one formula such as B / A, with percentage formatting. |
| conversion_rate | A flow that stalls. | Same shape as error_rate. |
| duration | A source that measures time. | A numeric property aggregation such as avg or p95 with math_property. value_format: "duration", unit of ms or s, and a non-negative snapshot. |
| revenue | A source that measures money. | A sum over the amount property with math_property. value_format: "currency", unit of an uppercase three-letter ISO code such as USD. |
| custom | A measurement that no kind above covers. | Still needs a live event or action query. |
A figure with no event or action query behind it stays in the prose. A database statistic, a build time read from another tool, or a number quoted from an external source has no query, so it cannot be a metric.
A noise report where nobody was hurt takes occurrences, never affected_users.
The server checks the aggregation for affected_users and affected_sessions only.
A plain event count formatted as duration or revenue passes validation and then prints a count beside a time or currency unit, so pick the aggregation from the row above rather than relying on the refusal.
An affected_users metric means distinct PostHog people, not sessions, events, requests, traces, groups, or the report's signal count.
affected_sessions means distinct sessions.
Group math and a formula are refuse