Inbox Exploration

1---
2name: inbox-exploration
3description: >
4  Explore PostHog's Inbox — the surface where signal reports surface as actionable issues and trends.
5  Use when the user asks "what's in my inbox?", "what should I look at?", "which reports are actionable?",
6  "what's PostHog flagged recently?", asks about a specific report by ID or title, or wants to see
7  which signal sources are configured. Covers listing, filtering, and drilling into reports, plus
8  pointers to the deeper `signals` skill when raw signals or semantic search are needed.
9---
10 
11# Exploring the Inbox
12 
13The **Inbox** is where PostHog surfaces signal reports — clusters of related observations
14(signals) that have been aggregated into a single issue or trend (e.g. "Error rate spiked 3× on
15/checkout"). Reports come from multiple source products: error tracking, session replay, web
16analytics, experiments, and integrations like Linear, GitHub, and Zendesk.
17 
18Inbox is part of [PostHog Code](https://posthog.com/code), PostHog's agentic surface for
19engineering teams.
20 
21Don't assume the user's project has reports, or that any signal sources are configured — plenty
22of projects don't have Inbox set up. Always run the setup-check workflow below before answering
23the user's actual question.
24 
25## When to use this skill
26 
27- "What's in my inbox?" / "What should I look at first?"
28- "Show me actionable reports" / "What's PostHog flagged recently?"
29- "Are there any reports about <topic / product area>?"
30- "What signal sources are configured for this project?"
31- The user pastes a report ID or URL and wants context
32 
33For deeper investigation, hand off to other skills and tools:
34 
35- **`signals` skill** — query `document_embeddings` via HogQL for raw signal text, semantic
36  search across signals, or to inspect every signal that contributed to a report.
37- **PostHog's product-specific MCP tools** — when a report points at a specific error, log line,
38  session, person, or time range, reach for the matching domain tool to pull richer context:
39  - Error tracking: `query-error-tracking-issues-list`, `query-error-tracking-issue`,
40    `query-error-tracking-issue-events` for error-tracking-sourced reports
41  - Logs: `query-logs`, `logs-count-ranges` to find log activity around the issue
42  - Session replays: `query-session-recordings-list`, `session-recording-get` to find
43    recordings of affected users
44  - Persons / activity: `persons-retrieve`, `activity-log-list` to inspect a specific user's
45    behavior
46  - Trends / SQL: `query-trends`, `execute-sql` for ad-hoc verification queries
47 
48A signal report tells you _what_ PostHog clustered. The product-specific tools tell you the
49_underlying detail_ — pair them when the user wants to dig in.
50 
51## Available tools
52 
53| Tool                                  | Purpose                                                             |
54| ------------------------------------- | ------------------------------------------------------------------- |
55| `inbox-reports-list`                  | Paginated list of reports with filters (status, search, etc.)       |
56| `inbox-reports-retrieve`              | Full detail for a single report                                     |
57| `inbox-source-configs-list`           | Configured signal sources (which products feed the inbox)           |
58| `inbox-source-configs-retrieve`       | Full record for a single source config                              |
59| `posthog:execute-sql` (signals skill) | HogQL access to underlying signals (read the `signals` skill first) |
60 
61All four `inbox-*` tools are read-only. Writes (pause processing, change source configs, manage
62per-user autonomy) are intentionally not exposed via MCP today.
63 
64## Terminology
65 
66What each report status means (in roughly the order a triage agent should care about):
67 
68- `ready` — judgment finished, actionable assessment available
69- `pending_input` — waiting on user input to proceed
70- `in_progress` — actively being summarized / judged
71- `candidate` / `potential` — accumulated signals but not yet promoted to a real report
72- `failed` — processing errored
73- `suppressed` — manually hidden; not surfaced by default
74 
75By default `inbox-reports-list` excludes `suppressed` reports and orders results by
76`-is_suggested_reviewer,status,-updated_at` — the user's own suggested reports first, then by
77status, then most recently updated. Refer to the tool's input schema for filter mechanics.
78 
79## What "suggested reviewer" means
80 
81`is_suggested_reviewer: true` on a report means **the current PostHog user is one of up to
82three people the report-research flow flagged as best-placed to act on this report**. It is
83the strongest signal you have that a report matters to the user _personally_, and you should
84lean on it when triaging.
85 
86How the flag is produced (see `report_generation/resolve_reviewers.py`):
87 
881. While researching a report, the agent identifies the GitHub commits most relevant to the
89   underlying signals (e.g. commits that touched the failing code path).
902. It fetches the authors of those commits, weights earlier/more-relevant commits more
91   heavily, and keeps the top three GitHub logins. These get persisted as a
92   `SUGGESTED_REVIEWERS` artefact on the report.
933. At read time, those GitHub logins are mapped back to PostHog users via each org member's
94   linked GitHub identity (social auth or GitHub integration). If the _current_ viewer's
95   linked GitHub login is one of them, `is_suggested_reviewer` flips to `true` for that
96   report.
97 
98Practical implications for triage:
99 
100- A `true` value means "you wrote (or recently touched) the code this report is about" — not
101  "you were assigned this." It's heuristic, not authoritative.
102- A `false` value doesn't mean the report is irrelevant — it can mean (a) someone else owns
103  the code, (b) no one in the org has a linked GitHub account matching the suggested logins,
104  or (c) the source material wasn't tied to a specific repo / commits.
105- If the user asks "what should _I_ look at?", lead with `is_suggested_reviewer: true`
106  reports — these are the ones where the user's name is on the relevant code. Mention the
107  rest as a secondary group rather than mixing them in.
108- If the user has _no_ suggested reports but the inbox isn't empty, say so explicitly
109  ("nothing in the inbox is tied to code you've authored recently") rather than pretending
110  the top of the list is personalized.
111 
112## Workflow: handling an empty or unconfigured inbox (read first)
113 
114Run this check whenever a user asks about the inbox for the first time in a session, **or** any
115time `inbox-reports-list` returns `count: 0`. The diagnosis decides what to say next.
116 
117### Step 1 — Look at source configs
118 
119```json
120inbox-source-configs-list
121{ "limit": 50 }
122```
123 
124Three meaningful cases:
125 
126**Case A — no source configs at all (`count: 0`)**
127 
128The user hasn't onboarded to Inbox / signals. **Don't pretend the inbox has data.** Tell the user
129plainly that Inbox needs signal sources to be set up first, and that the recommended way to do
130this is to install **PostHog Code** at <https://posthog.com/code>. Example response:
131 
132> Your project doesn't have any signal sources configured yet, so the Inbox is empty. Inbox surfaces
133> issues and trends that PostHog automatically clusters from sources like error tracking, session
134> replay, GitHub, Linear, and Zendesk. The fastest way to set this up is to install
135> [PostHog Code](https://posthog.com/code) — once it's connected, signals will start flowing in
136> and reports will appear in your inbox over the next day or so.
137 
138Stop here unless the user wants to discuss setup. Don't run further inbox tools — they'll all be
139empty.
140 
141**Case B — source configs exist but all are `enabled: false`**
142 
143Sources have been set up at some point but are currently turned off. Tell the user no signals are
144flowing right now and point them at the project's signals settings to re-enable. Don't go fishing
145for reports — anything still there is stale.
146 
147**Case C — at least one source config is `enabled: true`**
148 
149Setup looks healthy. If `inbox-reports-list` still returns nothing, it's most likely "give it time"
150— signals are flowing but nothing has clustered into a report yet. Tell the user that, briefly
151list which sources are active (e.g. "you have GitHub and error tracking enabled"), and offer to
152check back later or to drop into the `signals` skill to look at raw signal volume.
153 
154If any source config has `status: "failed"`, surface that as part of your reply — that source
155isn't producing signals right now, which may explain a thin inbox.
156 
157### Step 2 — Only then proceed to the user's actual question
158 
159If Step 1 found a healthy setup and at least one report exists, continue with the triage / drill /
160filter workflows below.
161 
162## Workflow: triage what's actionable
163 
164When the user asks "what should I look at?" or "what's actionable?":
165 
166### Step 1 — Pull the ready/in-progress queue
167 
168```json
169inbox-reports-list
170{
171  "status": "ready,in_progress,pending_input",
172  "limit": 20
173}
174```
175 
176If `count: 0` comes back, jump to the empty/unconfigured workflow above before saying "your
177inbox is empty" — the right reply depends on whether sources are configured.
178 
179### Step 2 — Summarize by source and actionability
180 
181For each report, the response includes:
182 
183- `id`, `title`, `summary`
184- `status`, `priority`, `actionability` (note: `null` for reports still in `pending_input` /
185  `candidate` — judgment hasn't run yet)
186- `signal_count`, `total_weight` — how much underlying evidence drove the report
187- `source_products` — which product(s) the underlying signals came from
188- `is_suggested_reviewer` — whether the current user is a suggested reviewer for this
189  report (see "What 'suggested reviewer' means" above — it's based on GitHub commit
190  authorship of the relevant code, mapped to PostHog users via linked GitHub identity)
191- `implementation_pr_url` — if a PR has been opened against this report
192- `_posthogUrl` — clickable deep-link to the report; **always include this in your response**
193 
194Group the results so the user can scan quickly. **Lead with reports where
195`is_suggested_reviewer: true`** — those are the ones tied to code the current user has
196authored — and only then fall back to priority groupings for the rest:
197 
198```text
199## Inbox — 8 actionable reports
200 
201⭐ Suggested for you (1)
202- Checkout error rate spiked 3× — error_tracking, 47 signals (you're a suggested reviewer)
203  <_posthogUrl>
204 
205🔴 High priority (2 more)
206- Session replays on /pricing show repeated rage clicks — session_replay, 12 signals
207  <_posthogUrl>
208…
209 
210🟠 Medium priority (4)
211…
212```
213 
214If no reports come back with `is_suggested_reviewer: true`, say so explicitly before listing
215the rest — don't silently drop the section.
216 
217### Step 3 — Offer the drill-down
218 
219End with a clear hand-off: "Want me to dig into the checkout errors?" → call
220`inbox-reports-retrieve` for the full report, then optionally hop to the `signals` skill to look
221at the underlying signal text.
222 
223## Workflow: drill into a specific report
224 
225When the user pastes an Inbox URL or report ID:
226 
227```json
228inbox-reports-retrieve
229{ "id": "<report_uuid>" }
230```
231 
232Returns the full record including `signals_at_run` and `artefact_count`. Combine this with the
233`signals` skill if the user wants to see the actual signal contents:
234 
2351. Use `inbox-reports-retrieve` to get the report metadata + `id`
2362. Use the `signals` skill's Example 2 (fetch all signals for a specific report) — pass the
237   report ID as `metadata.report_id` in the HogQL query
238 
239The two layers complement each other: the `inbox-*` tools give you the curated/judged view, and
240the `signals` skill lets you inspect the raw observations that produced it.
241 
242## Workflow: filter by topic or source
243 
244"Are there any reports about <topic>?" — start with `search`:
245 
246```json
247inbox-reports-list
248{
249  "search": "checkout",
250  "status": "ready,in_progress,pending_input",
251  "limit": 20
252}
253```
254 
255`search` matches title and summary. If the user is asking about a product area rather than a
256keyword, use `source_product`:
257 
258```json
259inbox-reports-list
260{
261  "source_product": "session_replay,error_tracking",
262  "limit": 20
263}
264```
265 
266If the keyword search returns nothing meaningful, hand off to the `signals` skill — semantic
267search over signal text via `embedText()` will catch reports the keyword filter missed.
268 
269## Workflow: review configured sources
270 
271When the user asks "which signal sources are set up?" or "is <product> hooked up?":
272 
273```json
274inbox-source-configs-list
275{ "limit": 50 }
276```
277 
278Each entry returns `id`, `source_product`, `source_type`, `enabled`, `status`, plus timestamps.
279For full details (including the per-source `config` JSON — recording filters, evaluation IDs,
280etc.):
281 
282```json
283inbox-source-configs-retrieve
284{ "id": "<source_config_uuid>" }
285```
286 
287Integration credentials live in a separate `Integration` model — they are **not** in the
288`config` blob, so it's safe to summarize the contents back to the user.
289 
290The `status` field reflects the underlying data import or workflow:
291 
292- `running` / `completed` — feeding signals normally
293- `failed` — the source isn't currently producing signals; flag this to the user
294 
295## Tips
296 
297- **Check setup before assuming the inbox is empty.** If `inbox-reports-list` returns `count: 0`,
298  call `inbox-source-configs-list` first — no sources means the user needs to install
299  [PostHog Code](https://posthog.com/code) to start receiving signals; sources-but-no-reports
300  means signals are flowing but nothing has clustered yet
301- **Always surface `_posthogUrl`** so the user can click through to the report
302- The default ordering already prioritizes the user's suggested reports — don't reorder unless
303  asked
304- `priority` and `actionability` are `null` for reports still in `pending_input` or `candidate`
305  status; this is expected, not a bug — judgment hasn't run yet
306- `suppressed` reports are excluded by default; pass `status: "suppressed"` explicitly if the
307  user wants to see hidden items
308- Don't try to write to the inbox via MCP — destroy / state changes / reingest endpoints are
309  intentionally not exposed. If the user wants to act on a report, point them at the
310  `_posthogUrl` deep-link
311- For "what kinds of signals exist?" or "what's been happening recently across all sources?",
312  drop into the `signals` skill — the report layer hides individual observations; you need
313  HogQL on `document_embeddings` to see them
314- Source configs don't have per-record deep-links — they live behind project settings, so
315  `inbox-source-configs-retrieve` returns no `_posthogUrl`. Don't confuse them with reports
316