new skill: analyze-report

plugins/mixpanel-mcp-eu/skills/analyze-report/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: analyze-report
+description: >
+  Read and explain a Mixpanel report or chart — what it shows, what's
+  notable, and what's worth a closer look. Use whenever the user asks to
+  interpret, explain, summarize, review, or break down an existing
+  chart, report, or saved query in Mixpanel. Trigger phrases:
+  "what does this chart show", "explain this report", "interpret this
+  chart", "summarize this for me", "what's notable here", "anything
+  weird in this chart", "tell me what's happening", "review this
+  insight", "walk me through this report", "what's the takeaway from
+  this". Also trigger when the user pastes a Mixpanel chart or report
+  URL and asks anything about it. Lean by default — surfaces what the
+  report shows and flags notable patterns, but does not chase root
+  causes. This skill = interpret WHAT a report shows; mxp-metric-diagnosis
+  = investigate WHY a metric moved. Do NOT trigger for building new charts,
+  reviewing entire dashboards, or full root-cause diagnostic workflows. Do NOT
+  trigger for root-cause diagnosis, anomaly investigation, or metric drift —
+  use mxp-metric-diagnosis for those. Requires Mixpanel MCP.
+compatibility: "Requires Mixpanel MCP. Works for any project the user has access to."
+---
+
+# Mixpanel Analyze Report
+
+Take a Mixpanel report or chart that already exists (or just got built)
+and turn it into a one-screen summary the customer can act on. The skill
+is **lean by default** — it explains what the report shows and flags
+what's notable, but does not chase root causes unless the customer asks.
+
+If the customer's follow-up is "why is this happening" or anything
+similar, treat that as a deeper root-cause investigation that is out of
+scope here. Flag what you see and stop; don't attempt multi-step RCA
+inline. This skill is built for fast interpretation.
+
+---
+
+## When this skill runs, it does four things in order
+
+1. **Locate the report** — by URL, ID, or fresh build
+2. **Pull the data** — re-run the query and parse the result
+3. **Read the shape** — trend, anomalies, breakdown distribution
+4. **Summarize for the customer** — what it shows, what's notable, what to do next
+
+---
+
+## Step 1 — Locate the report
+
+Three input modes. Detect which one applies from the customer's message:
+
+### Mode A — Customer provides a URL or chart/report ID
+
+Most common. Mixpanel report URLs look like
+`https://mixpanel.com/project/<project_id>/view/<board_id>/app/<chart>`
+or include `report_id=<id>`. Extract the ID(s).
+
+Use the relevant Mixpanel MCP tool to fetch the report's metadata and
+configuration — this gives you the events, properties, filters,
+breakdowns, date range, and chart type without having to ask the
+customer.
+
+If you can't resolve the URL/ID (404, permission error, malformed URL),
+say so plainly and ask if they meant a different report.
+
+### Mode B — Customer describes the report in natural language
+
+If the customer says "the DAU chart on my exec board" or "the funnel I
+built last week," they're pointing at an existing report but haven't
+given an ID. Use `Search-Entities` with `entity_types=['report']` to
+find candidates. Show the top 3 matches with their titles and dates,
+ask which one.
+
+If `Search-Entities` returns nothing useful, escalate to Mode C:
+
+> *"I can't find that report. Want to build it fresh and analyze that?"*
+
+### Mode C — Customer wants to analyze a report that doesn't exist yet
+
+The report has to be built before it can be analyzed. This skill builds
+it inline — it does not hand off to another skill. Do it in three calls:
+
+1. Call `Get-Query-Schema` to learn the valid shape for the query type
+   (insights, funnel, retention, flows) the customer is describing.
+2. Construct the query from the customer's description and call
+   `Run-Query` to execute it. This returns the result data and gives you
+   the configuration metadata you need for analysis.
+3. Optionally call `Display-Query` to render the chart so the customer
+   can see it alongside the summary.
+
+Once `Run-Query` returns, you already have the data and config — skip
+ahead to Step 3 and read the shape (Step 2 is only for pulling data on
+an existing report).
+
+If the customer asks for both in one turn ("build me a DAU chart and
+tell me what it shows"), do them as one workflow: build → analyze →
+present together.
+
+---
+
+## Step 2 — Pull the data
+
+For Mode A or B (existing report), call `Run-Query` with the same
+configuration as the saved report to get fresh data. Don't trust cached
+chart state — the customer may not have refreshed in days.
+
+For Mode C, you already have the `query_id` from the just-built chart.
+
+In both cases, you need:
+- The query result data (time series, breakdown values, etc.)
+- The chart configuration (events, properties, filters, date range,
+  chart type)
+
+Without configuration metadata, the analysis is shallow ("the line
+goes up") instead of grounded ("checkout volume rose 18% WoW, isolated
+to the iOS platform").
+
+---
+
+## Step 3 — Read the shape
+
+What to look for depends on chart type. Read the matching reference:
+
+- Insights → `references/read-insights.md`
+- Funnels → `references/read-funnels.md`
+- Retention → `references/read-retention.md`
+- Flows → `references/read-flows.md`
+
+Only load the reference file that matches the chart type — do not load
+all four.
+
+The references hold the **specific patterns** to look for in each
+chart type. The high-level rules across all types:
+
+### What to surface (always)
+
+- **The current value** — what the metric is right now
+- **Direction and magnitude of change** — is it up/down/flat, by how
+  much, vs. when
+- **The biggest contributor** — if there's a breakdown, which segment
+  drives the volume
+
+### What to flag (only if present)
+
+- **Step-change anomalies** — a single point that breaks the pattern
+- **Sustained drift** — the baseline has shifted (last 30 days look
+  different from prior 30 days)
+- **Suspicious-looking segments** — one segment doing all the work, or
+  a segment that suddenly disappeared
+- **Data quality cues** — a sudden jump that aligns with a deploy, an
+  event going to zero (looks like instrumentation broke)
+
+### What NOT to do
+
+- **Don't chase root cause.** If you spot a drop, flag it and stop.
+  Attributing the movement to a specific cause is a separate, deeper
+  workflow.
+- **Don't speculate about external causes.** Saying "this might be
+  because of holiday traffic" without evidence is hallucination.
+- **Don't recommend fixes.** The customer didn't ask for fixes. They
+  asked what the report shows.
+
+---
+
+## Step 4 — Summarize for the customer
+
+Output structure (always this shape, length scales with content):
+
+```
+**What this shows**
+[1–2 sentences: report subject, time window, current value]
+
+**The shape**
+[1–3 sentences: trend direction, magnitude, key inflection points]
+
+**Worth noting**
+[Bullet list — only items that meet the "flag" bar above. Skip if
+nothing notable.]
+
+**Want to dig in?**
+[Offer to either: (a) investigate why the movement happened, OR
+(b) recut the report with a different breakdown, filter, or date range
+if that would help]
+```
+
+Example output for a DAU chart that dipped:
+
+```
+**What this shows**
+Daily Active Users over the last 30 days. Currently at 142K DAU.
+
+**The shape**
+Flat through most of the month, with a clear step-down on March 18th
+— DAU dropped from ~150K to ~135K and hasn't recovered. The post-drop
+baseline is roughly 9% below the pre-drop average.
+
+**Worth noting**
+- The drop is a step-change, not a gradual decline — typical of a
+  deploy, instrumentation change, or external event.
+- Weekend dips are still present at the same magnitude — the issue
+  isn't a day-of-week shift.
+
+**Want to dig in?**
+The shape suggests a single trigger event around March 18th. Want me
+to dig into which segments are driving the drop?
+```
+
+Keep it tight. A customer reading this on a phone needs to get the
+takeaway in the first paragraph.
+
+---
+
+## Hybrid scope — when to stop
+
+Lean by default means: surface what's there, stop. The boundary is the
+"why" question. If the customer asks any of:
+
+- "Why did this drop / spike / change?"
+- "What's causing this?"
+- "Where is it coming from?"
+- "Is it specific users / regions / platforms?"
+
+…that's a root-cause investigation, which is a deeper, multi-step
+workflow. Don't try to answer it inline here. Flag what the data shows
+and offer the deeper dig as an explicit next step:
+
+> *"That's a root-cause question — it can take a few cuts to answer
+> properly. Want me to dig into the segments driving this?"*
+
+Do not silently expand the analysis. An unbounded "why" question turns
+a 30-second summary into a 10-minute investigation. Better to make the
+boundary explicit and let the customer opt in.
+
+---
+
+## Hard rules
+
+- **Always re-run the query.** Don't trust cached chart state.
+- **Configuration metadata grounds the analysis.** Without knowing the
+  events/filters, you can't tell the customer what they're looking at.
+- **Flag, don't diagnose.** Drift detection ≠ root cause.
+- **One screen of output.** Long analyses lose the customer.
+- **Make "why" an explicit next step.** Don't RCA inline.
+- **No speculation about external causes.** Stick to what the data
+  shows.
+
+---
+
+## Quick reference — MCP tools used
+
+| Step | Tool |
+|---|---|
+| 1 | `Get-Report` (for URL/ID), `Search-Entities` (for NL search) |
+| 1, Mode C | build the chart first, then come back with the `query_id` |
+| 2 | `Run-Query` |
+| 3 | (no new tool calls — pure analysis on the data already pulled) |
+| 4 | (output to user) |
+
+For chart-type-specific reading patterns, see `references/`.
+
+---
+
+## When to stop and redirect
+
+- Customer asks "why" → that's a root-cause investigation; flag and
+  offer it as a deeper next step, don't do it inline
+- Customer wants to modify or rebuild the chart → that's a build task,
+  out of scope for interpretation
+- Customer wants to analyze the whole dashboard → out of scope; this
+  skill reads a single report
+- Customer wants to clean up or manage old charts → out of scope

plugins/mixpanel-mcp-eu/skills/analyze-report/references/read-flows.md

@@ -0,0 +1,116 @@
+# Reading Flow charts — reference
+
+Use this reference when the chart being analyzed is a **Flow** (Sankey
+showing event-to-event transitions before or after an anchor event).
+
+---
+
+## What to read first
+
+1. **Anchor event volume** — how many users / events feed the anchor.
+   This is the denominator for everything downstream.
+
+2. **Top 1–3 paths** — what's the most common next event (or previous
+   event, for backward flows)? What % of users go that way?
+
+3. **Long tail** — how concentrated is the flow? If the top 3 paths
+   account for 80% of users, the flow has clear dominant patterns. If
+   the top 3 paths only account for 30%, the flow is fragmented.
+
+4. **Drop-off branch** — in forward flows, where do users *exit* the
+   product? In backward flows, where do they *enter* from?
+
+---
+
+## Patterns to flag
+
+### Highly concentrated flow
+
+If one path accounts for >70% of post-anchor activity, that path is
+the de facto product behavior. Flag it as the dominant pattern.
+
+> Flag as: *"After [anchor], [%] of users go to [next event] — that's
+> the dominant path. Other branches are minor."*
+
+### Highly fragmented flow
+
+If the top 3 paths account for <40% combined, users do many different
+things. This is either a power-user product (variety is healthy) or a
+confusing UX (users don't know what to do next).
+
+> Flag as: *"Flow is fragmented — top 3 paths account for only [%]
+> combined. Either deep variety in user behavior, or unclear next-step
+> guidance."*
+
+### High drop-off branch in forward flow
+
+A "drop-off" or "session end" branch claiming a large share is the
+flow chart's version of a funnel drop-off. Flag if it's a meaningful
+share (e.g., >30% drop off immediately after the anchor).
+
+> Flag as: *"[%] of users drop off immediately after [anchor] — they
+> don't proceed to any tracked event. Worth investigating where they
+> go."*
+
+### Unexpected next event
+
+If the customer's mental model is "users do A → B" but the flow shows
+"users do A → C", flag the surprise. The mental model and the data
+disagree.
+
+> Flag as: *"Most users go to [unexpected event] after [anchor] —
+> [expected event] is only [%]. The flow's not what you might
+> intuitively expect."*
+
+### Backward flow showing unexpected sources
+
+If the customer is looking at "what leads to [event]" and the top
+preceding event is a generic event (Page View, App Open) rather than
+a meaningful action, the flow isn't very informative. Suggest a
+deeper backward flow or filter out generic events.
+
+### Loops or repeating events
+
+If the flow shows the same event repeating (e.g., Page View → Page
+View → Page View), the chart needs a filter on a property to
+differentiate (which page?). Flag as a chart configuration issue.
+
+---
+
+## Common reader pitfalls
+
+**Confusing share % with conversion %**
+A flow showing "30% of users go to checkout after cart" is not the
+same as "30% of cart-add events convert." The flow share is users who
+did *that next event*, not conversion through a defined funnel.
+
+**Reading flows as session-bounded when they're not**
+Mixpanel flows aren't strictly session-bounded — events from different
+sessions hours or days apart can appear in the same flow. If the
+customer is asking about within-session behavior, flag this caveat.
+
+**Treating the anchor as a starting point when it isn't**
+Flows can be anchored anywhere, not just on entry events. If the
+customer says "user journey from signup" and the chart anchors on a
+mid-funnel event, the data isn't answering the question they asked.
+
+**Depth too shallow or too deep**
+Depth-1 flows show only one next event — useful for "what's the
+immediate next action" but not for path analysis. Depth-5+ flows are
+visually noisy. If the chart depth doesn't match the question, surface
+that.
+
+---
+
+## Output focus
+
+Flow summary should answer:
+- What's the dominant path?
+- How concentrated is the behavior?
+- What surprises (unexpected next/prior events, big drop-offs)?
+
+Skip:
+- Speculating on UX changes ("maybe the checkout button is
+  hidden" — out of scope)
+- Hypotheses on why users drop where they do (that's a root-cause
+  investigation, out of scope)