inbox-exploration

# Exploring the Inbox The **Inbox** is where PostHog surfaces signal reports — clusters of related observations (signals) that have been aggregated into a single issue or trend (e.g. "Error rate spiked 3× on /checkout"). Reports come from multiple source products: error tracking, session replay, web analytics, experiments, and integrations like Linear, GitHub, and Zendesk. Inbox is part of [PostHog Desktop](https://posthog.com/desktop), PostHog's agentic surface for engineering teams. Don't assume the user's project has reports, or that any signal sources are configured — plenty of projects don't have Inbox set up. Always run the setup-check workflow below before answering the user's actual question. ## When to use this skill - "What's in my inbox?" / "What should I look at first?" - "Show me actionable reports" / "What's PostHog flagged recently?" - "Are there any reports about <topic / product area>?" - "What signal sources are configured for this project?" - The user pastes a report ID or URL and wants context - "Fix this inbox item" / "turn this report into a PR" / "implement this report" — see _Workflow: act on an actionable report_ - "Dismiss this" / "snooze this report" / "mark this resolved" / "I've fixed this" — see _Workflow: resolve, dismiss, or snooze a report_ - "Get this merged" / "run the suggested prompt on this report" — see _Workflow: run an action on a report_ For deeper investigation, hand off to other skills and tools: - **`signals` skill** — query `document_embeddings` via HogQL for raw signal text, semantic search across signals, or to inspect every signal that contributed to a report. - **PostHog's product-specific MCP tools** — when a report points at a specific error, log line, session, person, or time range, reach for the matching domain tool to pull richer context: - Error tracking: `query-error-tracking-issues-list`, `query-error-tracking-issue`, `query-error-tracking-issue-events` for error-tracking-sourced reports - Logs: `query-logs`, `logs-count-ranges` to find log activity around the issue - Session replays: `query-session-recordings-list`, `session-recording-get` to find recordings of affected users - Persons / activity: `persons-retrieve`, `advanced-activity-logs-list` to inspect a specific user's behavior - Trends / SQL: `query-trends`, `execute-sql` for ad-hoc verification queries A signal report tells you _what_ PostHog clustered. The product-specific tools tell you the _underlying detail_ — pair them when the user wants to dig in. ## Available tools | Tool | Purpose | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `inbox-reports-list` | Paginated list of reports with filters (status, search, etc.) | | `inbox-reports-retrieve` | Full detail for a single report | | `inbox-reports-claim` | Claim or release a report, and optionally attach its implementation PR | | `inbox-report-artefacts-list` | A report's full work log — `signal_finding` evidence, status judgments, commits, task runs, notes (read-only) | | `inbox-report-artefacts-retrieve` | Full detail for a single artefact (read-only) | | `inbox-reports-set-state` | Resolve (`resolved`), dismiss (`suppressed`), or snooze (`potential`) a single report | | `inbox-reports-bulk-set-state` | Same transition for 1–100 reports in one call (per-id result) | | `inbox-report-actions-list` | The report's agent run actions (Get it merged, suggested prompts) and whether each can start now (read-only) | | `inbox-report-actions-run` | Start one of those actions as a background agent run linked to the report | | `inbox-source-configs-list` | Configured signal sources (which products feed the inbox) | | `inbox-source-configs-retrieve` | Full record for a single source config | | `inbox-source-configs-partial-update` | Toggle a source's `enabled` flag (or adjust its `config`) | | `posthog:execute-sql` (signals skill) | HogQL access to underlying signals (read the `signals` skill first) | The `inbox-reports-*-list` / `-retrieve`, `inbox-report-artefacts-list` / `-retrieve`, and `inbox-source-configs-*-list` / `-retrieve` tools are read-only. The exposed writes are `inbox-reports-set-state` (resolve / dismiss / snooze a single report), `inbox-reports-bulk-set-state` (the same transition for 1–100 reports in one call), `inbox-reports-claim` (claim / release / attach a PR), see _Workflow: resolve, dismiss, or snooze a report_ — `inbox-report-actions-run` (start an agent run from a report action), see _Workflow: run an action on a report_ — and `inbox-source-configs-partial-update`, which flips a source's `enabled` flag on or off (e.g. `{enabled: false}` to stop a source feeding the inbox); `-create` / `-update` exist too for standing a source up or replacing it wholesale. Pausing processing is not exposed via MCP. ## Terminology What each report status means (in roughly the order a triage agent should care about): - `ready` — judgment finished, actionable assessment available - `pending_input` — waiting on user input to proceed - `in_progress` — actively being summarized / judged - `candidate` / `potential` — accumulated signals but not yet promoted to a real report - `failed` — processing errored - `suppressed` — out of the inbox; not surfaced by default. A person or agent dismissed it, or a judge held it back before anyone reviewed it. See _Dismissed and held-back reports_ below - `resolved` — the work the report asked for is done. Terminal: a resolved report never re-promotes, so a recurrence starts a fresh report linked back to it. Set automatically when a linked implementation PR merges, or directly via `inbox-reports-set-state` (see the workflow below) By default `inbox-reports-list` excludes `suppressed` reports and orders results by `-is_suggested_reviewer,status,-updated_at` — the user's own suggested reports first, then by status, then most recently updated. Refer to the tool's input schema for filter mechanics. ## Dismissed and held-back reports A `suppressed` report has one of two origins. The inbox shows each origin in its own view, and `inbox-reports-list` accepts the same split through its `view` parameter: | `view` | Lists suppressed reports that… | `suppression_source` | | ----------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `dismissed` | a person or agent dismissed, or that were merged into another report, or whose PR closed unmerged | `dismissed` | | `held_back` | a judge suppressed before anyone reviewed them | `safety_judge`, `not_actionable`, `system` | Each suppressed row carries two fields that tell the origins apart: - `suppression_source` — `null` unless the status is `suppressed`. - `dismissed`: someone chose to remove the report. Read `dismissal_reason` and `dismissal_note` for the reason. - `safety_judge`: the safety judge marked the report unsafe. - `not_actionable`: the actionability judge marked the report not actionable. - `system`: the pipeline suppressed the report for a different reason. An older report that has no dismissal record and no judge verdict also shows this value. - `suppression_explanation` — the judge's explanation when the source is `safety_judge` or `not_actionable`. `null` for the other sources, or when the judge gave none. Only `dismissed` is a human or agent decision. The other sources are judge verdicts that nobody has reviewed, and a judge can be wrong. Do not tell the user they hid a held-back report. Include held-back reports in a review when: - the user asks what PostHog filtered out, or why an expected report is missing from the inbox - the user asks for a full review or audit of the inbox, not only the actionable queue - you deduplicate against the full inbox state before you file or merge a report For a held-back review, call `inbox-reports-list` with `{"view": "held_back"}`. Show the `suppression_source` and the `suppression_explanation` for each report, so the user can judge the verdict. If the user decides that a report is valid, restore it with `state: "potential"`. The report goes back to the status it had before the judge held it back. If the user agrees with the verdict, call `state: "suppressed"` with a `dismissal_reason`. The report then moves from `held_back` to `dismissed`. See _Workflow: resolve, dismiss, or snooze a report_ for both calls. ## What "suggested reviewer" means `is_suggested_reviewer: true` on a report means **the current PostHog user is one of up to three people the report-research flow flagged as best-placed to act on this report**. It is the strongest signal you have that a report matters to the user _personally_, and you should lean on it when triaging. How the flag is produced: 1. While researching a report, the agent identifies the GitHub commits most relevant to the underlying signals (e.g. commits that touched the failing code path). 2. It fetches the authors of those commits, weights earlier/more-relevant commits more heavily, and keeps the top three GitHub logins. These get persisted as a `SUGGESTED_REVIEWERS` artefact on the report. 3. At read time, those GitHub logins are mapped back to PostHog users via each org member's linked GitHub identity (social auth or GitHub integration). If the _current_ viewer's linked GitHub login is one of them, `is_suggested_reviewer` flips to `true` for that report. A reviewer can also be stored by PostHog `user_uuid` (a scout or a person naming an org member directly), which matches the viewer without any GitHub link. The flag is forced to `false` on a `failed` report and on a `ready` report judged `not_actionable`, whatever reviewers they carry, so read `suggested_reviewers` directly when auditing routing. Practical implications for triage: - A `true` value means "you are a suggested reviewer for this report": a plausible owner, not an assignee. When the pipeline derived the reviewers, that usually means you wrote (or recently touched) the relevant code; when a scout or a person named you by `user_uuid`, it means they judged you the owner. It's a recommendation, not authoritative. - A `false` value doesn't mean the report is irrelevant — it can mean (a) someone else owns the code, (b) the suggested logins came from commit history and no org member has that GitHub account linked (a reviewer set by `user_uuid` doesn't have this problem), or (c) the source material wasn't tied to a specific repo / commits. - If the user asks "what should _I_ look at?", lead with `is_suggested_reviewer: true` reports: these are the ones routed to the user as a likely owner. Mention the rest as a secondary group rather than mixing them in. - If the user has _no_ suggested reports but the inbox isn't empty, say so explicitly ("nothing in the inbox is tied to code you've authored recently") rather than pretending the top of the list is personalized. ## Workflow: handling an empty or unconfigured inbox (read first) Run this check whenever a user asks about the inbox for the first time in a session, **or** any time `inbox-reports-list` returns `count: 0`. The diagnosis decides what to say next. ### Step 1 — Look at source configs ```json inbox-source-configs-list { "limit": 50 } ``` Three meaningful cases: **Case A — no source configs at all (`count: 0`)** The user hasn't onboarded to Inbox / signals. **Don't pretend the inbox has data.** Tell the user plainly that Inbox needs signal sources to be set up first, and that the recommended way to do this is to install **PostHog Desktop** at <https://posthog.com/desktop>. Example response: > Your project doesn't have any signal sources configured yet, so the Inbox is empty. Inbox surfaces > issues and trends that PostHog automatically clusters from sources like error tracking, session > replay, GitHub, Linear, and Zendesk. The fastest way to set this up is to install > [PostHog Desktop](https://posthog.com/desktop) — once it's connected, signals will start flowing in > and reports will appear in your inbox over the next day or so. Stop here unless the user wants to discuss setup. Don't run further inbox tools — they'll all be empty. **Case B — source configs exist but all are `enabled: false`** Sources have been set up at some point but are currently turned off. Tell the user no signals are flowing right now. You can re-enable a source directly with `inbox-source-configs-partial-update { "id": "<source_config_uuid>", "enabled": true }` (confirm with the user first), or they can flip it on from the project's signals settings. Don't go fishing for reports — anything still there is stale. **Case C — at least one source config is `enabled: true`** Setup looks healthy. If `inbox-reports-list` still returns nothing, it's most likely "give it time" — signals are flowing but nothing has clustered into a report yet. Tell the user that, briefly list which sources are active (e.g. "you have GitHub and error tracking enabled"), and offer to check back later or to drop into the `signals` skill to look at raw signal volume. If any source config has `status: "failed"`, surface that as part of your reply — that source isn't producing signals right now, which may explain a thin inbox. ### Step 2 — Only then proceed to the user's actual question If Step 1 found a healthy setup and at least one report exists, continue with the triage / drill / filter workflows below. ## Workflow: triage what's actionable When the user asks "what should I look at?" or "what's actionable?": ### Step 1 — Pull the ready/in-progress queue ```json inbox-reports-list { "status": "ready,in_progress,pending_input", "limit": 20 } ``` If `count: 0` comes back, jump to the empty/unconfigured workflow above before saying "your inbox is empty" — the right reply depends on whether sources are configured. A claimed report keeps its pipeline status, so this queue also returns work someone else already owns. Add `"unclaimed": true` when the user is asking what is free to pick up, and `"assignee": "me"` to list what the caller already owns and may want to resume. ### Step 2 — Summarize by source and actionability For each report, the response includes: - `id`, `title`, `summary` - `status`, `priority`, `actionability` (note: `null` for reports still in `pending_input` / `candidate` — judgment hasn't run yet) - `signal_count`, `total_weight` — how much underlying evidence drove the report - `source_products` — which product(s) the underlying signals came from - `is_suggested_reviewer` — whether the current user is a suggested reviewer for this report (see "What 'suggested reviewer' means" above — it's based on GitHub commit authorship of the relevant code, mapped to PostHog users via linked GitHub identity) - `pull_requests` — if a PR has been opened against this report - `work_state` — `unclaimed`, `working`, `in_review`, or `done` - `assignee` — who claimed the report (a user, an internal task, or an external agent), or `null` when nobody has. Say so when you list a report someone else owns, so it doesn't read as free work - `_posthogUrl` — clickable deep-link to the report; **always include this in your response** Group the results so the user can scan quickly. **Lead with reports where `is_suggested_reviewer: true`** — those are the ones tied to code the current user has authored — and only then fall back to priority groupings for the rest: ```text ## Inbox — 8 actionable reports ⭐ Suggested for you (1) - Checkout error rate spiked 3× — error_tracking, 47 signals (you're a suggested reviewer) <_posthogUrl> 🔴 High priority (2 more) - Session replays on /pricing show repeated rage clicks — session_replay, 12 signals <_posthogUrl> … 🟠 Medium priority (4) … ``` If no reports come back with `is_suggested_reviewer: true`, say so explicitly before listing the rest — don't silently drop the section. ### Step 3 — Offer the drill-down End with a clear hand-off: "Want me to dig into the checkout errors?" → call `inbox-reports-retrieve` for the full report, then optionally hop to the `signals` skill to look at the underlying signal text. ## Workflow: drill into a specific report When the user pastes an Inbox URL or report ID: ```json inbox-reports-retrieve { "id": "<report_uuid>" } ``` Returns the full record including `signals_at_run` and `artefact_count`. Then read the report's work log: ```json inbox-report-artefacts-list { "report_id": "<report_uuid>" } ``` This returns the report's evidence (`signal_finding`), the judgments behind its status/priority/actionability (`safety_judgment`, `actionability_judgment`, `priority_judgment`,