From 1a23ccbdd10ab0131cc45bf73bfb51d0827f4055 Mon Sep 17 00:00:00 2001 From: Yonah Dorfman Date: Wed, 8 Jul 2026 17:13:16 +0300 Subject: [PATCH 1/3] Changes to make business context work with the existing setup and pass the AI readiness score --- README.md | 1 + .../skills/mixpanel-ai-readiness/SKILL.md | 143 ++++++++++++++++++ .../commands/enrich-data.md | 31 ++++ .../commands/import-context.md | 60 ++++++++ .../commands/setup-context.md | 71 +++++++++ .../mixpanel-ai-readiness/commands/status.md | 48 ++++++ .../mixpanel-ai-readiness/commands/target.md | 37 +++++ .../references/context-template.md | 89 +++++++++++ .../references/import-mapping.md | 32 ++++ .../references/interview-questions.md | 73 +++++++++ .../skills/mixpanel-ai-readiness/SKILL.md | 143 ++++++++++++++++++ .../commands/enrich-data.md | 31 ++++ .../commands/import-context.md | 60 ++++++++ .../commands/setup-context.md | 71 +++++++++ .../mixpanel-ai-readiness/commands/status.md | 48 ++++++ .../mixpanel-ai-readiness/commands/target.md | 37 +++++ .../references/context-template.md | 89 +++++++++++ .../references/import-mapping.md | 32 ++++ .../references/interview-questions.md | 73 +++++++++ .../skills/mixpanel-ai-readiness/SKILL.md | 143 ++++++++++++++++++ .../commands/enrich-data.md | 31 ++++ .../commands/import-context.md | 60 ++++++++ .../commands/setup-context.md | 71 +++++++++ .../mixpanel-ai-readiness/commands/status.md | 48 ++++++ .../mixpanel-ai-readiness/commands/target.md | 37 +++++ .../references/context-template.md | 89 +++++++++++ .../references/import-mapping.md | 32 ++++ .../references/interview-questions.md | 73 +++++++++ 28 files changed, 1753 insertions(+) create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/SKILL.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/enrich-data.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/import-context.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/setup-context.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/status.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/target.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/context-template.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/import-mapping.md create mode 100644 plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/interview-questions.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/SKILL.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/enrich-data.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/import-context.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/setup-context.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/status.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/target.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/context-template.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/import-mapping.md create mode 100644 plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/interview-questions.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/SKILL.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/enrich-data.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/import-context.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/setup-context.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/status.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/target.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/context-template.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/import-mapping.md create mode 100644 plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/interview-questions.md diff --git a/README.md b/README.md index 01770ad..df4ef3b 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Plugins that give AI agents Mixpanel expertise. Built on the [Agent Skills](http | [`manage-experiment`](plugins/mixpanel-mcp/skills/manage-experiment/) | Coaches an agent through any phase of a Mixpanel experiment — designing before launch (hypothesis, metrics, sizing, statistical model, advanced features, pre-launch checks) and interpreting after launch (read results, ship / iterate / kill / wait, health checks, segment breakdowns, session replays). | | [`manage-feature-flags`](plugins/mixpanel-mcp/skills/manage-feature-flags/) | Coaches an agent through Mixpanel feature-flag work — picking the right flag-shaped tool (Feature Gate vs Dynamic Config vs Experiment), staged rollouts, the kill switch, exposure debugging, archive/restore, and SDK call patterns. | | [`manage-lexicon`](plugins/mixpanel-mcp/skills/manage-lexicon/) | Audits, scores, enriches, and cleans up Lexicon metadata (events and properties) for a Mixpanel project. Supports scoring health, bulk-filling descriptions/tags, resetting metadata, triaging data quality issues, and managing tags. | +| [`mixpanel-ai-readiness`](plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/) | Sets up business context (org and project level) and delegates Lexicon enrichment so Mixpanel's AI assistants understand a customer's data. Supports status scoring, importing existing context, interview-based setup, and choosing org vs. project scope. | | [`tracking-implementation`](plugins/mixpanel-mcp/skills/tracking-implementation/) | Guides an agent through Mixpanel analytics implementation. Supports Quick Start, Full Implementation, Add Tracking, and Audit modes. | ### Internal skills diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/SKILL.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/SKILL.md new file mode 100644 index 0000000..f732540 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/SKILL.md @@ -0,0 +1,143 @@ +--- +name: mixpanel-ai-readiness +license: Apache-2.0 +description: > + Set up everything Mixpanel's AI assistants need to work well on a customer's + data: business context (org and project level) AND Lexicon metadata (event + descriptions, property descriptions, tags) that lets the agent understand the + data itself. Use whenever a user wants to get a project or org "ready for the + AI / agent / MCP", set up business context for the first time, import context + written down elsewhere, fill gaps, or check how AI-ready a project is across + the business and data layers. Also use on phrasings like — "set us up for + Mixpanel AI", "the agent keeps asking what our events mean", "make our project + agent-ready", "we have this in Notion, can you pull it in", "how ready are we + for the agent". Owns the business-context layer directly; delegates + event/property/tag enrichment to the manage-lexicon skill. Do NOT use for: + building dashboards; metric investigations; deleting data. Requires Mixpanel + MCP. Works best with manage-lexicon available. +--- + +# Mixpanel AI Readiness + +This skill gets a customer's Mixpanel setup ready for AI assistants (the in-product agent and MCP clients). "Ready" means two layers are in place: + +1. **Business context** — markdown the agent reads first, at org level (who the company is) and project level (how a project is set up). The agent uses it to know the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** +2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has to guess what each event and property means on every query. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. + +The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. + +--- + +# Critical constraints (read before any write) + +Properties of the underlying APIs, not preferences. + +1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. The skill MUST read existing context, merge in memory, show a full diff, and require `CONFIRM` before every write. Never write a partial document. +2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. +3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. +4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. +5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. +6. **Delegate Lexicon work; don't duplicate it.** Event/property/tag enrichment runs through `manage-lexicon`. If that skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. + +--- + +# Components + +## Canonical commands + +Loaded on demand from `commands/`. + +| Command | File | Match if message contains any of | +|---|---|---| +| `status` | `commands/status.md` | how ready, ai-ready, score, audit, what's missing, check our setup | +| `import-context` | `commands/import-context.md` | import, we already have, pull from, from notion/doc/drive, paste | +| `setup-context` | `commands/setup-context.md` | set up context, configure context, interview, create context | +| `enrich-data` | `commands/enrich-data.md` | event descriptions, property descriptions, tags, clean up events, lexicon | +| `target` | `commands/target.md` | switch level, org vs project, change target, where should this live | + +If a message matches more than one, show the Command menu. The natural full-onboarding path is: `status` → `import-context` (or `setup-context`) → `enrich-data` → `status`. + +## Command menu + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + Mixpanel AI Readiness — [Org Name] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + Business context layer + 1. Status — Score readiness across BOTH layers + 2. Import context — Pull context you already have (connector or file) + 3. Setup context — Interview to build context from scratch + 4. Target — Org level, project level, or both + Data layer (Lexicon) + 5. Enrich data — Event/property descriptions + tags (via manage-lexicon) + 6. Exit +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## Session vocabulary + +| Key | Shape | Description | +|---|---|---| +| `org_id`, `org_name` | string | Active organization. | +| `target_level` | `"org"`\|`"project"`\|`"both"` | Where context is written. | +| `project_id`, `project_name` | string | Active project, when in scope. | +| `caller_role` | map | Resolved role at org and project — the permission gate. | +| `existing_context` | map | `{ org, project }` current context, read before any write. | +| `imported_source` | map | Raw text pulled from a connector/file, plus its origin, pre-mapping. | +| `schema_facts` | map | Derived top events/properties, integrations, timezone. Timestamped. | +| `interview_answers` | map | Section-keyed answers, for gaps not covered by import. | +| `draft_context` | map | `{ org, project }` composed markdown pending preview/confirm. | +| `lexicon_score` | map | Coverage summary returned from `manage-lexicon` (for the unified status). | + +## Behaviour rules + +1. **No phase narration.** Output questions, previews, diffs, confirmation prompts, errors, results. Not "I'll now read your doc…". +2. **Import before interview.** Always offer to pull existing context first. Interview is the gap-filler, not the default. +3. **Read before write, always.** Populate `existing_context` for the target before composing. The diff is computed against it. +4. **Preview + diff before every context write.** Show the full proposed document and what changes vs current. Require literal `CONFIRM`. `EXPORT` saves a local `.md` without writing. Anything else cancels. +5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT`. +6. **Never overwrite populated content silently.** Existing sections are preserved and shown; the user chooses per section. +7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. +8. **Ground everything.** Only what import or interview or `schema_facts` support. Uncertainty → Open Questions, never hedged prose. +9. **Quarantine volatile facts.** Schema counts/lists go only in the fenced, timestamped Schema Snapshot section. +10. **Delegate Lexicon, surface its result.** `enrich-data` hands off to `manage-lexicon` and captures `lexicon_score` so `status` can report both layers. +11. **Audit trail.** After every successful write, append `ai-readiness-runs/[ISO-timestamp]-[command].json` with org/target/project, command, sections or entities written, counts. +12. **`exit` always valid.** + +--- + +# Execution + +## 1. Resolve organization and target +Identify the org. Determine `target_level` (infer from the request, else ask: org / project / both). Resolve `project_id` if project is in scope. If Mixpanel MCP is unavailable, tell the user to connect it and stop. + +## 2. Permission pre-check +Resolve `caller_role` for each target. Surface any level the user can't edit up front; adjust target or offer `EXPORT`. + +## 3. Read existing context +Read current context for each target into `existing_context`. Mandatory — diffs and merges compute against it. + +## 3.5. Offer import-context first (if context is empty or thin) +**BEFORE setup-context or the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): + +**Always ask first:** +``` +Your [org/project] context is currently [empty/minimal]. + +Do you have existing business context written down somewhere? + • Notion, Google Drive, Confluence, or other connected source + • A file or text block you can paste + • Or I can interview you from scratch + +Where should I look? (or type 'interview' to skip import) +``` + +Only proceed to `setup-context` or the menu if the user explicitly declines to import or types "interview" / "skip" / "scratch". This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule). + +## 4. Command loop +Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry, return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). + +## Reference files +- `references/context-template.md` — fixed org and project section templates (who/what/where/why/how), aligned to Mixpanel's native context generation so output is consistent with the in-product "Generate with AI" button. +- `references/interview-questions.md` — question bank per section, including the authority question. +- `references/import-mapping.md` — how to map an arbitrary source doc onto the template, what to keep, what to drop. diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/enrich-data.md new file mode 100644 index 0000000..4b107fb --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/enrich-data.md @@ -0,0 +1,31 @@ +# Command: enrich-data + +Set up the Lexicon metadata the agent needs to understand the data itself: event descriptions, property descriptions, and tags. This command **delegates to the `manage-lexicon` skill** run inline — it does not reimplement enrichment. Its job is to hand off cleanly and capture the result for the unified readiness status. + +**Session reads:** `org_id`, `project_id`, `project_name`, `caller_role` +**Session writes:** `lexicon_score` + +--- + +## Step 1 — Preconditions + +- A project must be in scope (`project_id`). If only org-level context was being worked on, ask which project to enrich — Lexicon is per-project. +- The caller needs project owner/admin to write Lexicon. Check `caller_role`; if missing, say so and offer to have an admin run this step. +- Confirm `manage-lexicon` is available. If it is not, tell the user the data layer can't be set up automatically right now, point them to the `manage-lexicon` skill in the Mixpanel skills repository, and return — do **not** reimplement event/property/tag editing here. + +## Step 2 — Hand off to manage-lexicon + +Invoke `manage-lexicon` for this `project_id`. Drive it through, in order: + +1. **`score-lexicon`** — get the current metadata health (description coverage on events and properties, tag coverage). Capture the score. +2. **`enrich-and-tag`** — fill empty event descriptions, empty property descriptions, and add tags. Respect that skill's own rules: fill-only-empty (never overwrite existing metadata), add tags rather than replace, and its preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. + +Let `manage-lexicon` own its previews and confirmations. This command does not duplicate or wrap those prompts; the user interacts with manage-lexicon's flow directly. + +## Step 3 — Capture result + +After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise run `score-lexicon` once more to capture the after state. + +## Follow-on + +Offer: "Want me to re-run **status** so you can see the full AI-readiness picture across context and data?" → hands to `status`. diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/import-context.md new file mode 100644 index 0000000..dc72da2 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/import-context.md @@ -0,0 +1,60 @@ +# Command: import-context + +Pull business knowledge the customer has already written down, map it onto the fixed template, show what mapped and what's still empty, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. + +**Session reads:** `org_id`, `target_level`, `project_id`, `caller_role`, `existing_context`, `schema_facts` +**Session writes:** `imported_source`, `interview_answers` (for gaps), `draft_context` + +--- + +## Step 1 — Find the source + +Ask where the existing context lives, and accept any of: + +- **A connected MCP connector** — e.g. Notion, Google Drive, Confluence, a wiki, a knowledge source. Search it for the relevant doc (tracking plan, data dictionary, analytics README, PRD, "about our metrics" page). If several connectors are connected, ask which to search, or search the most likely and confirm the hit. +- **A pasted block or uploaded file** — the user drops text or a file directly. + +Do not assume which connector. Detect what's connected; if nothing relevant is, fall back to paste/file. If the user names a connector that isn't connected, tell them and offer paste/file or `setup-context` instead. + +Store the raw retrieved text and its origin in `imported_source`. Never write this raw text to Mixpanel — it is input, not output. + +## Step 2 — Map onto the template + +Using `references/import-mapping.md`, map the source onto `references/context-template.md` for the target level(s): + +- Pull each template section's content from the source where it exists. +- **Drop** what doesn't belong: meeting notes, roadmap, changelogs, anything time-bound or operational that isn't durable context. +- Do not invent. If a section has no source material, leave it empty and mark it for the gap step. +- Schema-derived facts still come from `schema_facts` (Step via setup-context's schema pull), not from the doc — the doc's own numbers are likely stale. + +## Step 3 — Show the mapping + +Present a coverage view so the user sees exactly what the import produced: + +``` +Mapped from [source]: + ✓ Business / domain ← from doc + ✓ North star ← from doc + ✓ Vocabulary & acronyms ← from doc + ⚠ Qualified-user definition — partial, needs confirmation + ✗ Authority & governance — not found in source + ✗ Key dashboards — not found in source +``` + +Anything ✗ or ⚠ is a gap. + +## Step 4 — Fill gaps (mini-interview) + +For gaps only, ask the targeted questions from `references/interview-questions.md`. Always include the **authority** question and the **qualified-user** question if the import didn't cover them — these are the highest-value fields and source docs usually lack them. Record in `interview_answers`. Unknowns → Open Questions. + +## Step 5 — Compose, preview, diff, confirm + +Identical to `setup-context` Steps 3–4: compose `draft_context` to the template (durable content first, schema facts fenced + timestamped, uncertainty in Open Questions), respect the 50k cap, show the full document plus a diff against `existing_context`. Only literal `CONFIRM` proceeds to write. `EXPORT` saves a local `.md`. For `both`, confirm each level separately. + +## Step 6 — Back up, then write + +Back up existing context per SKILL.md's "Back up before every write" rule, then write the composed document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +## Follow-on + +After writing: "Want me to **enrich the data layer** (event/property descriptions and tags) so the agent understands your schema too? I'll run that through manage-lexicon." → hands to `enrich-data`. diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/setup-context.md new file mode 100644 index 0000000..05a318a --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/setup-context.md @@ -0,0 +1,71 @@ +# Command: setup-context + +Build business context from scratch via a guided interview, when the customer has nothing written down to import. Pulls schema facts first to make questions concrete, drafts to the fixed template, previews with a diff, and writes on `CONFIRM`. Handles org level, project level, or both. + +**Session reads:** `org_id`, `target_level`, `project_id`, `project_name`, `caller_role`, `existing_context` +**Session writes:** `schema_facts`, `interview_answers`, `draft_context` + +> **CRITICAL:** If the customer *does* have existing context somewhere, prefer `import-context` and use this only to fill gaps. **Always offer import first** before starting this command. See SKILL.md's "Offer import-context first" step. + +--- + +## Step 0 — Confirm the user wants interview-based setup + +**ALWAYS ask this first** (unless they explicitly invoked "setup-context" or typed "interview"): + +``` +Do you have existing business context written down somewhere I could pull from? + • Notion, Confluence, Google Drive, wiki, tracking plan, etc. + • Or paste/upload a file + +If yes, we'll use import-context instead (faster and more complete). +If no, I'll interview you from scratch. + +Which would you prefer? +``` + +If they have a source, hand off to `import-context` immediately. Only proceed with this command if they confirm they have nothing to import. + +## Step 1 — Research and pull schema first + +Before asking the user anything (per `references/interview-questions.md`): +- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. +- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped. Counts never go into prose, only the fenced Schema Snapshot. Partial failure: continue, note the gap in Open Questions. + +## Step 2 — Interview (gaps and internal-only facts) + +Work `references/interview-questions.md`, in small batches, seeded with research and `schema_facts`. Present the web-researched Business/Segments drafts for correction rather than asking from scratch. + +Mandatory, do not skip: +- **North star, scoped to Mixpanel**: which *Mixpanel-trackable* metric best reflects success, anchored to real events. Capture any true north star that lives outside Mixpanel (revenue, NRR, GMV) separately, with the closest in-Mixpanel proxy, so the agent doesn't chase data that isn't here. +- **Qualified/active user definition** in this data. +- **Authority**: who owns the schema and canonical reports, whose conventions the agent should follow, when to defer to a human vs. create new entities. Highest-value field. +- **Vocabulary**: ask first whether a glossary/data dictionary exists and import it; only interview term-by-term if there's no source. + +Record in `interview_answers`. Unknowns → Open Questions, never guessed. + +## Step 3 — Compose draft + +Fill `references/context-template.md`: durable `tldr;` first (what/where/when/who/how/why, 1–3 sentences each, linking deeper); qualitative sections from answers; all schema facts in the fenced, timestamped Schema Snapshot; unsupported items in Open Questions. Respect the 50k cap (trim Schema Snapshot first). + +## Step 4 — Preview, diff, confirm + +Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged) — required because writes are full-replace. Prompt: + +``` +Write this to [org / project: NAME] business context? + CONFIRM — commit this exact document (replaces current context at this level) + EXPORT — save draft to a local .md file, don't write to Mixpanel + edit — tell me what to change + exit — discard +``` + +Only literal `CONFIRM` commits. For `both`, confirm each level separately. + +## Step 5 — Back up, then write + +Back up existing context per SKILL.md's "Back up before every write" rule, then write the full document for the level. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +## Follow-on + +"Now set up the **data layer** (event/property descriptions + tags via manage-lexicon) so the agent understands your schema?" → hands to `enrich-data`. diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/status.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/status.md new file mode 100644 index 0000000..f548706 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/status.md @@ -0,0 +1,48 @@ +# Command: status + +The unified AI-readiness readout. Scores both layers in one view — business context completeness *and* Lexicon coverage — and tells the user exactly what's missing and which command fixes it. This is the re-engagement hook: run it on any account to see where it stands and what to do next. It is read-only. + +**Session reads:** `org_id`, `org_name`, `target_level`, `project_id`, `project_name`, `existing_context`, `lexicon_score` +**Session writes:** `existing_context`, `lexicon_score` (refreshes both) + +--- + +## Step 1 — Business-context layer + +For the org and (if a project is in scope) the project: + +- Read current context if not already in `existing_context`. +- Score completeness against `references/context-template.md`: which required sections are present and non-empty. Weight the high-value sections (north star, qualified-user definition, authority & governance) more heavily — a doc with vocabulary but no authority section is weaker than the raw section count suggests. +- Flag staleness: if a Schema Snapshot section exists, compare its timestamp to now and warn if old. + +## Step 2 — Data layer (Lexicon) + +If a project is in scope and `manage-lexicon` is available, run its `score-lexicon` (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. + +## Step 3 — Present one readout + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + AI Readiness — [Project Name] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + BUSINESS CONTEXT + Org level ●●●●○ present, missing: customer segments + Project level ●●○○○ thin — no authority section, no qualified-user def + + DATA (LEXICON) + Event descriptions 45% + Property descriptions 30% + Events tagged 12% + + TOP GAPS (most impact first) + 1. Project authority & governance → import-context / setup-context + 2. Property descriptions (30%) → enrich-data + 3. Event tags (12%) → enrich-data +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +Order gaps by impact on agent quality, not by raw percentage: a missing authority section or qualified-user definition hurts the agent more than a few undescribed low-volume events. Each gap names the command that fixes it. + +## Follow-on + +Offer the single highest-impact next step as a direct handoff (e.g. "Start with **import-context** for the project — want me to go?"). Don't dump the whole menu; recommend the one move. diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/target.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/target.md new file mode 100644 index 0000000..ec6ba68 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/target.md @@ -0,0 +1,37 @@ +# Command: target + +Change which level(s) the skill writes business context to: org-level, project-level, or both. + +**Session reads:** `org_id`, `org_name`, `project_id`, `project_name`, `caller_role` +**Session writes:** `target_level` + +--- + +## Prompt + +Ask which level the user wants to target: + +``` +Where should business context live? + 1. Org level only — shared across all projects + 2. Project level only — scoped to [Project Name] + 3. Both — org context + project-specific context +``` + +## Validate permissions + +Check `caller_role` for the chosen target(s). If the user lacks write permission for a level, surface it and offer alternatives: + +- If they can't write to org: "You need org owner/admin to write org-level context. Want to target project only?" +- If they can't write to project: "You need project owner/admin to write project context. Want to target org only, or export locally?" + +## Set and confirm + +Update `target_level` to `"org"`, `"project"`, or `"both"`. Confirm back to the user: "Got it — targeting [level(s)]." + +## Follow-on + +Offer the next natural step based on where they are in the workflow: +- If they haven't run `status` yet: "Want me to check your AI readiness **status** first?" +- If they have context to import: "Ready to **import** your existing context?" +- Otherwise: "Ready to **set up** context from scratch?" diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/context-template.md new file mode 100644 index 0000000..af5cfc0 --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/context-template.md @@ -0,0 +1,89 @@ +# Context Template + +Fixed section structure for generated context. Adapted from the who/what/where/why/how framework Mixpanel uses for native context generation, so skill output stays consistent with the in-product "Generate with AI" button. **Structure is fixed; only content varies.** Used by `import-context`, `setup-context`, and scored by `status`. + +--- + +## ORG-LEVEL TEMPLATE + +```markdown +# [Company] — Organization Context + +## tldr; +- **What**: One line — what the company does and its business model. +- **Who**: One line — primary customer segments and who uses Mixpanel internally. +- **How we measure success**: One line — the Mixpanel-trackable metric that best reflects success, plus any true north star that lives outside Mixpanel. + +## Business +[2–4 sentences: product, business model, how the company makes money. Durable facts only.] + +## North Star & Key Metrics +- **North star (in Mixpanel)**: [the Mixpanel-trackable metric that best reflects success + why] +- **Supporting metrics (in Mixpanel)**: [list] +- **True north star outside Mixpanel**: [e.g. revenue/NRR/GMV in another tool, + closest Mixpanel proxy — or "none, north star is trackable here"] +- **Definition of a qualified/active user**: [the exact rule the agent should apply] + +## Customer Segments +[Named segments and what distinguishes them.] + +## Internal Vocabulary & Acronyms +[Term — meaning. Anything the agent would otherwise misread.] + +## Open Questions +[Anything not yet known, phrased as questions. Never fabricate.] +``` + +--- + +## PROJECT-LEVEL TEMPLATE + +```markdown +# [Project] — Project Context + +## tldr; +- **What**: One line — what this project tracks and for which product/surface. +- **Where**: One line — where data comes from (SDK, server, warehouse) and key integrations. +- **Who**: One line — who has authority over this project's schema and reports. +- **How**: One line — how analysis is done here (custom entities, conventions). +- **Why**: One line — the business decisions this project's analysis feeds. + +## Domain & Vocabulary +[What the product is, what the events represent, who the tracked end-user is.] + +## Event Taxonomy & Naming Conventions +[How events/properties are named and organized. Casing, prefixes, the canonical +patterns the agent should follow when referring to or creating entities.] + +## Authority & Governance +[Who owns the schema and canonical reports. Whose conventions to emulate. When +the agent should defer to a human instead of creating new entities. This section +prevents the agent from copying a non-authoritative user's chaotic style.] + +## Key Dashboards & Reports +[Named canonical surfaces and what each is for.] + +## Definition of Active/Qualified User (this project) +[If it differs from org level.] + +## Schema Snapshot + +``` +Top events: [list] +Key properties: [list] +Integrations in use: [list] +Timezone: [tz] +``` + +## Open Questions +[Anything not grounded in answers, import, or schema, phrased as questions.] +``` + +--- + +## Rules + +- `tldr;` H3s are 1–3 sentences each. Terse. Point to deeper sections, don't duplicate. +- Schema-derived facts live **only** in Schema Snapshot, fenced and timestamped. +- No quantity-in-prose ("project has 26 users") — goes stale, is bloat. +- Hedging language not allowed in the body. Uncertainty → Open Questions. +- Imported content is mapped here section-by-section; it never enters raw. diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/import-mapping.md new file mode 100644 index 0000000..8db094d --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/import-mapping.md @@ -0,0 +1,32 @@ +# Import Mapping + +How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template. Never paste raw source into Mixpanel. + +## Mapping table (source → template section) + +| If the source has… | Map to | +|---|---| +| "About us", company overview, what we do/sell | Business / Domain & Vocabulary | +| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | +| Definition of active/qualified/engaged user, MAU/WAU logic | Definition of Qualified User | +| Customer types, segments, personas, tiers | Customer Segments | +| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | +| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | +| Data owner, schema owner, "ask X before adding events", RACI | Authority & Governance | +| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | +| Default project guidance, which project for what | Conventions & Defaults (org) | + +## What to drop (do not map) + +- Meeting notes, decisions logs, dated standups. +- Roadmap, upcoming features, "Q3 plans" — time-bound, not durable context. +- Changelogs, migration notes, ticket references. +- Anything that contradicts the live schema — flag it as an Open Question rather than importing it. +- Raw numbers/counts — schema facts come from the live pull, fenced and timestamped, not from the doc. + +## Rules + +- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. +- **Preserve the customer's own vocabulary.** If they call it "design partners" not "enterprise customers", keep their term — the agent should speak their language. +- **Attribute nothing you can't ground.** If the doc implies an owner but doesn't name one, that's an Open Question, not an Authority entry. +- **Show your work.** The coverage view (import-context Step 3) must make clear which sections came from the source and which are still empty, so the user trusts the result and knows what the gap-interview will cover. diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/interview-questions.md new file mode 100644 index 0000000..c30872d --- /dev/null +++ b/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/interview-questions.md @@ -0,0 +1,73 @@ +# Interview Questions + +Starter question bank, grouped by template section. **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` where noted, ask in small batches. Unknown answers → Open Questions, never guessed. + +--- + +## Before interviewing — research and pre-fill + +Do these first, so the interview is mostly confirmation, not blank-filling: + +1. **Web search the company.** What it does, business model, customers/segments. Draft the **Business** and **Customer Segments** sections from public sources, then present for correction (see below). Don't ask these cold. +2. **Pull the schema** into `schema_facts` (top events, key properties) — needed to anchor the north-star and event questions to what actually exists in Mixpanel. +3. **Check for a definitions source.** Before asking vocab questions, ask if one exists and import it instead. + +--- + +## ORG LEVEL + +### Business *(pre-filled from web search — confirm, don't ask)* +- Here's what I found about the company: [drafted summary]. Is this right? Anything to fix or add? +- Anything about the business model or how you make money that the public description gets wrong? + +### Customer Segments *(pre-filled from web search — confirm, don't ask)* +- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? + +### North Star & Key Metrics *(must be Mixpanel-trackable)* +- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[Verified] Query Run`, activations, something else?") +- What are the 2–3 supporting metrics **in Mixpanel** underneath it? +- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR, GMV in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. +- How do you define an "active" or "qualified" user in this data? (the exact rule) + +### Vocabulary & Acronyms *(ask for a source first)* +- Do you have a glossary, data dictionary, or definitions page anywhere? If so, point me to it and I'll pull from it. +- If not: what internal terms or acronyms would the agent misread? Term + meaning. (focus on words that mean something specific in *your* data — "activation", "engaged", "churned") + +--- + +## PROJECT LEVEL + +### Domain & Vocabulary +- What product or surface does this project track? (web app, mobile, backend, a specific feature) +- Who is the end-user whose behavior shows up here? (your customer, an internal team, a machine/service) +- *(Seed with schema_facts)* Your highest-volume events are `[X]` and `[Y]` — one line each, what do those represent? + +### Event Taxonomy & Naming Conventions +- How are events named here? Casing or prefix rules? (e.g. "Verb Noun", `[Verified]` prefix, snake_case) +- *(Seed with schema_facts)* I see properties like `[A]` and `[B]` — what do they mean, and which matter most for analysis? +- Any events or properties that look important but should be ignored? (test, deprecated, internal-only) + +### Authority & Governance +- Who owns the schema and the canonical reports in this project? +- Whose naming and conventions should the agent follow when unsure? +- When should the agent stop and ask a human instead of creating a new event, property, or report itself? + +### Key Dashboards & Reports +- Which dashboards/reports are the canonical, trusted ones? What is each for? +- Where would you point a new team member first? + +### Qualified User (this project) +- Does "active" or "qualified" user mean something different here than at the org level? If so, what? + +### Why / Business Impact +- What decisions does this project's analysis actually drive, and who acts on them? + +--- + +## Always ask if not already covered + +Highest-value fields; source docs and web search usually lack them. Don't close an interview without them: + +1. **Qualified/active user definition** — applied on almost every agent question. +2. **Authority** — who owns the schema and whose conventions to follow. Prevents the agent copying a random user's messy style. +3. **North star, scoped to Mixpanel** — anchored to events that exist here, with any out-of-Mixpanel true north star noted separately. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/SKILL.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/SKILL.md new file mode 100644 index 0000000..f732540 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/SKILL.md @@ -0,0 +1,143 @@ +--- +name: mixpanel-ai-readiness +license: Apache-2.0 +description: > + Set up everything Mixpanel's AI assistants need to work well on a customer's + data: business context (org and project level) AND Lexicon metadata (event + descriptions, property descriptions, tags) that lets the agent understand the + data itself. Use whenever a user wants to get a project or org "ready for the + AI / agent / MCP", set up business context for the first time, import context + written down elsewhere, fill gaps, or check how AI-ready a project is across + the business and data layers. Also use on phrasings like — "set us up for + Mixpanel AI", "the agent keeps asking what our events mean", "make our project + agent-ready", "we have this in Notion, can you pull it in", "how ready are we + for the agent". Owns the business-context layer directly; delegates + event/property/tag enrichment to the manage-lexicon skill. Do NOT use for: + building dashboards; metric investigations; deleting data. Requires Mixpanel + MCP. Works best with manage-lexicon available. +--- + +# Mixpanel AI Readiness + +This skill gets a customer's Mixpanel setup ready for AI assistants (the in-product agent and MCP clients). "Ready" means two layers are in place: + +1. **Business context** — markdown the agent reads first, at org level (who the company is) and project level (how a project is set up). The agent uses it to know the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** +2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has to guess what each event and property means on every query. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. + +The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. + +--- + +# Critical constraints (read before any write) + +Properties of the underlying APIs, not preferences. + +1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. The skill MUST read existing context, merge in memory, show a full diff, and require `CONFIRM` before every write. Never write a partial document. +2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. +3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. +4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. +5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. +6. **Delegate Lexicon work; don't duplicate it.** Event/property/tag enrichment runs through `manage-lexicon`. If that skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. + +--- + +# Components + +## Canonical commands + +Loaded on demand from `commands/`. + +| Command | File | Match if message contains any of | +|---|---|---| +| `status` | `commands/status.md` | how ready, ai-ready, score, audit, what's missing, check our setup | +| `import-context` | `commands/import-context.md` | import, we already have, pull from, from notion/doc/drive, paste | +| `setup-context` | `commands/setup-context.md` | set up context, configure context, interview, create context | +| `enrich-data` | `commands/enrich-data.md` | event descriptions, property descriptions, tags, clean up events, lexicon | +| `target` | `commands/target.md` | switch level, org vs project, change target, where should this live | + +If a message matches more than one, show the Command menu. The natural full-onboarding path is: `status` → `import-context` (or `setup-context`) → `enrich-data` → `status`. + +## Command menu + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + Mixpanel AI Readiness — [Org Name] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + Business context layer + 1. Status — Score readiness across BOTH layers + 2. Import context — Pull context you already have (connector or file) + 3. Setup context — Interview to build context from scratch + 4. Target — Org level, project level, or both + Data layer (Lexicon) + 5. Enrich data — Event/property descriptions + tags (via manage-lexicon) + 6. Exit +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## Session vocabulary + +| Key | Shape | Description | +|---|---|---| +| `org_id`, `org_name` | string | Active organization. | +| `target_level` | `"org"`\|`"project"`\|`"both"` | Where context is written. | +| `project_id`, `project_name` | string | Active project, when in scope. | +| `caller_role` | map | Resolved role at org and project — the permission gate. | +| `existing_context` | map | `{ org, project }` current context, read before any write. | +| `imported_source` | map | Raw text pulled from a connector/file, plus its origin, pre-mapping. | +| `schema_facts` | map | Derived top events/properties, integrations, timezone. Timestamped. | +| `interview_answers` | map | Section-keyed answers, for gaps not covered by import. | +| `draft_context` | map | `{ org, project }` composed markdown pending preview/confirm. | +| `lexicon_score` | map | Coverage summary returned from `manage-lexicon` (for the unified status). | + +## Behaviour rules + +1. **No phase narration.** Output questions, previews, diffs, confirmation prompts, errors, results. Not "I'll now read your doc…". +2. **Import before interview.** Always offer to pull existing context first. Interview is the gap-filler, not the default. +3. **Read before write, always.** Populate `existing_context` for the target before composing. The diff is computed against it. +4. **Preview + diff before every context write.** Show the full proposed document and what changes vs current. Require literal `CONFIRM`. `EXPORT` saves a local `.md` without writing. Anything else cancels. +5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT`. +6. **Never overwrite populated content silently.** Existing sections are preserved and shown; the user chooses per section. +7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. +8. **Ground everything.** Only what import or interview or `schema_facts` support. Uncertainty → Open Questions, never hedged prose. +9. **Quarantine volatile facts.** Schema counts/lists go only in the fenced, timestamped Schema Snapshot section. +10. **Delegate Lexicon, surface its result.** `enrich-data` hands off to `manage-lexicon` and captures `lexicon_score` so `status` can report both layers. +11. **Audit trail.** After every successful write, append `ai-readiness-runs/[ISO-timestamp]-[command].json` with org/target/project, command, sections or entities written, counts. +12. **`exit` always valid.** + +--- + +# Execution + +## 1. Resolve organization and target +Identify the org. Determine `target_level` (infer from the request, else ask: org / project / both). Resolve `project_id` if project is in scope. If Mixpanel MCP is unavailable, tell the user to connect it and stop. + +## 2. Permission pre-check +Resolve `caller_role` for each target. Surface any level the user can't edit up front; adjust target or offer `EXPORT`. + +## 3. Read existing context +Read current context for each target into `existing_context`. Mandatory — diffs and merges compute against it. + +## 3.5. Offer import-context first (if context is empty or thin) +**BEFORE setup-context or the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): + +**Always ask first:** +``` +Your [org/project] context is currently [empty/minimal]. + +Do you have existing business context written down somewhere? + • Notion, Google Drive, Confluence, or other connected source + • A file or text block you can paste + • Or I can interview you from scratch + +Where should I look? (or type 'interview' to skip import) +``` + +Only proceed to `setup-context` or the menu if the user explicitly declines to import or types "interview" / "skip" / "scratch". This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule). + +## 4. Command loop +Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry, return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). + +## Reference files +- `references/context-template.md` — fixed org and project section templates (who/what/where/why/how), aligned to Mixpanel's native context generation so output is consistent with the in-product "Generate with AI" button. +- `references/interview-questions.md` — question bank per section, including the authority question. +- `references/import-mapping.md` — how to map an arbitrary source doc onto the template, what to keep, what to drop. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/enrich-data.md new file mode 100644 index 0000000..4b107fb --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/enrich-data.md @@ -0,0 +1,31 @@ +# Command: enrich-data + +Set up the Lexicon metadata the agent needs to understand the data itself: event descriptions, property descriptions, and tags. This command **delegates to the `manage-lexicon` skill** run inline — it does not reimplement enrichment. Its job is to hand off cleanly and capture the result for the unified readiness status. + +**Session reads:** `org_id`, `project_id`, `project_name`, `caller_role` +**Session writes:** `lexicon_score` + +--- + +## Step 1 — Preconditions + +- A project must be in scope (`project_id`). If only org-level context was being worked on, ask which project to enrich — Lexicon is per-project. +- The caller needs project owner/admin to write Lexicon. Check `caller_role`; if missing, say so and offer to have an admin run this step. +- Confirm `manage-lexicon` is available. If it is not, tell the user the data layer can't be set up automatically right now, point them to the `manage-lexicon` skill in the Mixpanel skills repository, and return — do **not** reimplement event/property/tag editing here. + +## Step 2 — Hand off to manage-lexicon + +Invoke `manage-lexicon` for this `project_id`. Drive it through, in order: + +1. **`score-lexicon`** — get the current metadata health (description coverage on events and properties, tag coverage). Capture the score. +2. **`enrich-and-tag`** — fill empty event descriptions, empty property descriptions, and add tags. Respect that skill's own rules: fill-only-empty (never overwrite existing metadata), add tags rather than replace, and its preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. + +Let `manage-lexicon` own its previews and confirmations. This command does not duplicate or wrap those prompts; the user interacts with manage-lexicon's flow directly. + +## Step 3 — Capture result + +After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise run `score-lexicon` once more to capture the after state. + +## Follow-on + +Offer: "Want me to re-run **status** so you can see the full AI-readiness picture across context and data?" → hands to `status`. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/import-context.md new file mode 100644 index 0000000..dc72da2 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/import-context.md @@ -0,0 +1,60 @@ +# Command: import-context + +Pull business knowledge the customer has already written down, map it onto the fixed template, show what mapped and what's still empty, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. + +**Session reads:** `org_id`, `target_level`, `project_id`, `caller_role`, `existing_context`, `schema_facts` +**Session writes:** `imported_source`, `interview_answers` (for gaps), `draft_context` + +--- + +## Step 1 — Find the source + +Ask where the existing context lives, and accept any of: + +- **A connected MCP connector** — e.g. Notion, Google Drive, Confluence, a wiki, a knowledge source. Search it for the relevant doc (tracking plan, data dictionary, analytics README, PRD, "about our metrics" page). If several connectors are connected, ask which to search, or search the most likely and confirm the hit. +- **A pasted block or uploaded file** — the user drops text or a file directly. + +Do not assume which connector. Detect what's connected; if nothing relevant is, fall back to paste/file. If the user names a connector that isn't connected, tell them and offer paste/file or `setup-context` instead. + +Store the raw retrieved text and its origin in `imported_source`. Never write this raw text to Mixpanel — it is input, not output. + +## Step 2 — Map onto the template + +Using `references/import-mapping.md`, map the source onto `references/context-template.md` for the target level(s): + +- Pull each template section's content from the source where it exists. +- **Drop** what doesn't belong: meeting notes, roadmap, changelogs, anything time-bound or operational that isn't durable context. +- Do not invent. If a section has no source material, leave it empty and mark it for the gap step. +- Schema-derived facts still come from `schema_facts` (Step via setup-context's schema pull), not from the doc — the doc's own numbers are likely stale. + +## Step 3 — Show the mapping + +Present a coverage view so the user sees exactly what the import produced: + +``` +Mapped from [source]: + ✓ Business / domain ← from doc + ✓ North star ← from doc + ✓ Vocabulary & acronyms ← from doc + ⚠ Qualified-user definition — partial, needs confirmation + ✗ Authority & governance — not found in source + ✗ Key dashboards — not found in source +``` + +Anything ✗ or ⚠ is a gap. + +## Step 4 — Fill gaps (mini-interview) + +For gaps only, ask the targeted questions from `references/interview-questions.md`. Always include the **authority** question and the **qualified-user** question if the import didn't cover them — these are the highest-value fields and source docs usually lack them. Record in `interview_answers`. Unknowns → Open Questions. + +## Step 5 — Compose, preview, diff, confirm + +Identical to `setup-context` Steps 3–4: compose `draft_context` to the template (durable content first, schema facts fenced + timestamped, uncertainty in Open Questions), respect the 50k cap, show the full document plus a diff against `existing_context`. Only literal `CONFIRM` proceeds to write. `EXPORT` saves a local `.md`. For `both`, confirm each level separately. + +## Step 6 — Back up, then write + +Back up existing context per SKILL.md's "Back up before every write" rule, then write the composed document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +## Follow-on + +After writing: "Want me to **enrich the data layer** (event/property descriptions and tags) so the agent understands your schema too? I'll run that through manage-lexicon." → hands to `enrich-data`. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/setup-context.md new file mode 100644 index 0000000..05a318a --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/setup-context.md @@ -0,0 +1,71 @@ +# Command: setup-context + +Build business context from scratch via a guided interview, when the customer has nothing written down to import. Pulls schema facts first to make questions concrete, drafts to the fixed template, previews with a diff, and writes on `CONFIRM`. Handles org level, project level, or both. + +**Session reads:** `org_id`, `target_level`, `project_id`, `project_name`, `caller_role`, `existing_context` +**Session writes:** `schema_facts`, `interview_answers`, `draft_context` + +> **CRITICAL:** If the customer *does* have existing context somewhere, prefer `import-context` and use this only to fill gaps. **Always offer import first** before starting this command. See SKILL.md's "Offer import-context first" step. + +--- + +## Step 0 — Confirm the user wants interview-based setup + +**ALWAYS ask this first** (unless they explicitly invoked "setup-context" or typed "interview"): + +``` +Do you have existing business context written down somewhere I could pull from? + • Notion, Confluence, Google Drive, wiki, tracking plan, etc. + • Or paste/upload a file + +If yes, we'll use import-context instead (faster and more complete). +If no, I'll interview you from scratch. + +Which would you prefer? +``` + +If they have a source, hand off to `import-context` immediately. Only proceed with this command if they confirm they have nothing to import. + +## Step 1 — Research and pull schema first + +Before asking the user anything (per `references/interview-questions.md`): +- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. +- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped. Counts never go into prose, only the fenced Schema Snapshot. Partial failure: continue, note the gap in Open Questions. + +## Step 2 — Interview (gaps and internal-only facts) + +Work `references/interview-questions.md`, in small batches, seeded with research and `schema_facts`. Present the web-researched Business/Segments drafts for correction rather than asking from scratch. + +Mandatory, do not skip: +- **North star, scoped to Mixpanel**: which *Mixpanel-trackable* metric best reflects success, anchored to real events. Capture any true north star that lives outside Mixpanel (revenue, NRR, GMV) separately, with the closest in-Mixpanel proxy, so the agent doesn't chase data that isn't here. +- **Qualified/active user definition** in this data. +- **Authority**: who owns the schema and canonical reports, whose conventions the agent should follow, when to defer to a human vs. create new entities. Highest-value field. +- **Vocabulary**: ask first whether a glossary/data dictionary exists and import it; only interview term-by-term if there's no source. + +Record in `interview_answers`. Unknowns → Open Questions, never guessed. + +## Step 3 — Compose draft + +Fill `references/context-template.md`: durable `tldr;` first (what/where/when/who/how/why, 1–3 sentences each, linking deeper); qualitative sections from answers; all schema facts in the fenced, timestamped Schema Snapshot; unsupported items in Open Questions. Respect the 50k cap (trim Schema Snapshot first). + +## Step 4 — Preview, diff, confirm + +Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged) — required because writes are full-replace. Prompt: + +``` +Write this to [org / project: NAME] business context? + CONFIRM — commit this exact document (replaces current context at this level) + EXPORT — save draft to a local .md file, don't write to Mixpanel + edit — tell me what to change + exit — discard +``` + +Only literal `CONFIRM` commits. For `both`, confirm each level separately. + +## Step 5 — Back up, then write + +Back up existing context per SKILL.md's "Back up before every write" rule, then write the full document for the level. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +## Follow-on + +"Now set up the **data layer** (event/property descriptions + tags via manage-lexicon) so the agent understands your schema?" → hands to `enrich-data`. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/status.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/status.md new file mode 100644 index 0000000..f548706 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/status.md @@ -0,0 +1,48 @@ +# Command: status + +The unified AI-readiness readout. Scores both layers in one view — business context completeness *and* Lexicon coverage — and tells the user exactly what's missing and which command fixes it. This is the re-engagement hook: run it on any account to see where it stands and what to do next. It is read-only. + +**Session reads:** `org_id`, `org_name`, `target_level`, `project_id`, `project_name`, `existing_context`, `lexicon_score` +**Session writes:** `existing_context`, `lexicon_score` (refreshes both) + +--- + +## Step 1 — Business-context layer + +For the org and (if a project is in scope) the project: + +- Read current context if not already in `existing_context`. +- Score completeness against `references/context-template.md`: which required sections are present and non-empty. Weight the high-value sections (north star, qualified-user definition, authority & governance) more heavily — a doc with vocabulary but no authority section is weaker than the raw section count suggests. +- Flag staleness: if a Schema Snapshot section exists, compare its timestamp to now and warn if old. + +## Step 2 — Data layer (Lexicon) + +If a project is in scope and `manage-lexicon` is available, run its `score-lexicon` (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. + +## Step 3 — Present one readout + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + AI Readiness — [Project Name] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + BUSINESS CONTEXT + Org level ●●●●○ present, missing: customer segments + Project level ●●○○○ thin — no authority section, no qualified-user def + + DATA (LEXICON) + Event descriptions 45% + Property descriptions 30% + Events tagged 12% + + TOP GAPS (most impact first) + 1. Project authority & governance → import-context / setup-context + 2. Property descriptions (30%) → enrich-data + 3. Event tags (12%) → enrich-data +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +Order gaps by impact on agent quality, not by raw percentage: a missing authority section or qualified-user definition hurts the agent more than a few undescribed low-volume events. Each gap names the command that fixes it. + +## Follow-on + +Offer the single highest-impact next step as a direct handoff (e.g. "Start with **import-context** for the project — want me to go?"). Don't dump the whole menu; recommend the one move. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/target.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/target.md new file mode 100644 index 0000000..ec6ba68 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/target.md @@ -0,0 +1,37 @@ +# Command: target + +Change which level(s) the skill writes business context to: org-level, project-level, or both. + +**Session reads:** `org_id`, `org_name`, `project_id`, `project_name`, `caller_role` +**Session writes:** `target_level` + +--- + +## Prompt + +Ask which level the user wants to target: + +``` +Where should business context live? + 1. Org level only — shared across all projects + 2. Project level only — scoped to [Project Name] + 3. Both — org context + project-specific context +``` + +## Validate permissions + +Check `caller_role` for the chosen target(s). If the user lacks write permission for a level, surface it and offer alternatives: + +- If they can't write to org: "You need org owner/admin to write org-level context. Want to target project only?" +- If they can't write to project: "You need project owner/admin to write project context. Want to target org only, or export locally?" + +## Set and confirm + +Update `target_level` to `"org"`, `"project"`, or `"both"`. Confirm back to the user: "Got it — targeting [level(s)]." + +## Follow-on + +Offer the next natural step based on where they are in the workflow: +- If they haven't run `status` yet: "Want me to check your AI readiness **status** first?" +- If they have context to import: "Ready to **import** your existing context?" +- Otherwise: "Ready to **set up** context from scratch?" diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/context-template.md new file mode 100644 index 0000000..af5cfc0 --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/context-template.md @@ -0,0 +1,89 @@ +# Context Template + +Fixed section structure for generated context. Adapted from the who/what/where/why/how framework Mixpanel uses for native context generation, so skill output stays consistent with the in-product "Generate with AI" button. **Structure is fixed; only content varies.** Used by `import-context`, `setup-context`, and scored by `status`. + +--- + +## ORG-LEVEL TEMPLATE + +```markdown +# [Company] — Organization Context + +## tldr; +- **What**: One line — what the company does and its business model. +- **Who**: One line — primary customer segments and who uses Mixpanel internally. +- **How we measure success**: One line — the Mixpanel-trackable metric that best reflects success, plus any true north star that lives outside Mixpanel. + +## Business +[2–4 sentences: product, business model, how the company makes money. Durable facts only.] + +## North Star & Key Metrics +- **North star (in Mixpanel)**: [the Mixpanel-trackable metric that best reflects success + why] +- **Supporting metrics (in Mixpanel)**: [list] +- **True north star outside Mixpanel**: [e.g. revenue/NRR/GMV in another tool, + closest Mixpanel proxy — or "none, north star is trackable here"] +- **Definition of a qualified/active user**: [the exact rule the agent should apply] + +## Customer Segments +[Named segments and what distinguishes them.] + +## Internal Vocabulary & Acronyms +[Term — meaning. Anything the agent would otherwise misread.] + +## Open Questions +[Anything not yet known, phrased as questions. Never fabricate.] +``` + +--- + +## PROJECT-LEVEL TEMPLATE + +```markdown +# [Project] — Project Context + +## tldr; +- **What**: One line — what this project tracks and for which product/surface. +- **Where**: One line — where data comes from (SDK, server, warehouse) and key integrations. +- **Who**: One line — who has authority over this project's schema and reports. +- **How**: One line — how analysis is done here (custom entities, conventions). +- **Why**: One line — the business decisions this project's analysis feeds. + +## Domain & Vocabulary +[What the product is, what the events represent, who the tracked end-user is.] + +## Event Taxonomy & Naming Conventions +[How events/properties are named and organized. Casing, prefixes, the canonical +patterns the agent should follow when referring to or creating entities.] + +## Authority & Governance +[Who owns the schema and canonical reports. Whose conventions to emulate. When +the agent should defer to a human instead of creating new entities. This section +prevents the agent from copying a non-authoritative user's chaotic style.] + +## Key Dashboards & Reports +[Named canonical surfaces and what each is for.] + +## Definition of Active/Qualified User (this project) +[If it differs from org level.] + +## Schema Snapshot + +``` +Top events: [list] +Key properties: [list] +Integrations in use: [list] +Timezone: [tz] +``` + +## Open Questions +[Anything not grounded in answers, import, or schema, phrased as questions.] +``` + +--- + +## Rules + +- `tldr;` H3s are 1–3 sentences each. Terse. Point to deeper sections, don't duplicate. +- Schema-derived facts live **only** in Schema Snapshot, fenced and timestamped. +- No quantity-in-prose ("project has 26 users") — goes stale, is bloat. +- Hedging language not allowed in the body. Uncertainty → Open Questions. +- Imported content is mapped here section-by-section; it never enters raw. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/import-mapping.md new file mode 100644 index 0000000..8db094d --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/import-mapping.md @@ -0,0 +1,32 @@ +# Import Mapping + +How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template. Never paste raw source into Mixpanel. + +## Mapping table (source → template section) + +| If the source has… | Map to | +|---|---| +| "About us", company overview, what we do/sell | Business / Domain & Vocabulary | +| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | +| Definition of active/qualified/engaged user, MAU/WAU logic | Definition of Qualified User | +| Customer types, segments, personas, tiers | Customer Segments | +| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | +| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | +| Data owner, schema owner, "ask X before adding events", RACI | Authority & Governance | +| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | +| Default project guidance, which project for what | Conventions & Defaults (org) | + +## What to drop (do not map) + +- Meeting notes, decisions logs, dated standups. +- Roadmap, upcoming features, "Q3 plans" — time-bound, not durable context. +- Changelogs, migration notes, ticket references. +- Anything that contradicts the live schema — flag it as an Open Question rather than importing it. +- Raw numbers/counts — schema facts come from the live pull, fenced and timestamped, not from the doc. + +## Rules + +- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. +- **Preserve the customer's own vocabulary.** If they call it "design partners" not "enterprise customers", keep their term — the agent should speak their language. +- **Attribute nothing you can't ground.** If the doc implies an owner but doesn't name one, that's an Open Question, not an Authority entry. +- **Show your work.** The coverage view (import-context Step 3) must make clear which sections came from the source and which are still empty, so the user trusts the result and knows what the gap-interview will cover. diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/interview-questions.md new file mode 100644 index 0000000..c30872d --- /dev/null +++ b/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/interview-questions.md @@ -0,0 +1,73 @@ +# Interview Questions + +Starter question bank, grouped by template section. **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` where noted, ask in small batches. Unknown answers → Open Questions, never guessed. + +--- + +## Before interviewing — research and pre-fill + +Do these first, so the interview is mostly confirmation, not blank-filling: + +1. **Web search the company.** What it does, business model, customers/segments. Draft the **Business** and **Customer Segments** sections from public sources, then present for correction (see below). Don't ask these cold. +2. **Pull the schema** into `schema_facts` (top events, key properties) — needed to anchor the north-star and event questions to what actually exists in Mixpanel. +3. **Check for a definitions source.** Before asking vocab questions, ask if one exists and import it instead. + +--- + +## ORG LEVEL + +### Business *(pre-filled from web search — confirm, don't ask)* +- Here's what I found about the company: [drafted summary]. Is this right? Anything to fix or add? +- Anything about the business model or how you make money that the public description gets wrong? + +### Customer Segments *(pre-filled from web search — confirm, don't ask)* +- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? + +### North Star & Key Metrics *(must be Mixpanel-trackable)* +- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[Verified] Query Run`, activations, something else?") +- What are the 2–3 supporting metrics **in Mixpanel** underneath it? +- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR, GMV in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. +- How do you define an "active" or "qualified" user in this data? (the exact rule) + +### Vocabulary & Acronyms *(ask for a source first)* +- Do you have a glossary, data dictionary, or definitions page anywhere? If so, point me to it and I'll pull from it. +- If not: what internal terms or acronyms would the agent misread? Term + meaning. (focus on words that mean something specific in *your* data — "activation", "engaged", "churned") + +--- + +## PROJECT LEVEL + +### Domain & Vocabulary +- What product or surface does this project track? (web app, mobile, backend, a specific feature) +- Who is the end-user whose behavior shows up here? (your customer, an internal team, a machine/service) +- *(Seed with schema_facts)* Your highest-volume events are `[X]` and `[Y]` — one line each, what do those represent? + +### Event Taxonomy & Naming Conventions +- How are events named here? Casing or prefix rules? (e.g. "Verb Noun", `[Verified]` prefix, snake_case) +- *(Seed with schema_facts)* I see properties like `[A]` and `[B]` — what do they mean, and which matter most for analysis? +- Any events or properties that look important but should be ignored? (test, deprecated, internal-only) + +### Authority & Governance +- Who owns the schema and the canonical reports in this project? +- Whose naming and conventions should the agent follow when unsure? +- When should the agent stop and ask a human instead of creating a new event, property, or report itself? + +### Key Dashboards & Reports +- Which dashboards/reports are the canonical, trusted ones? What is each for? +- Where would you point a new team member first? + +### Qualified User (this project) +- Does "active" or "qualified" user mean something different here than at the org level? If so, what? + +### Why / Business Impact +- What decisions does this project's analysis actually drive, and who acts on them? + +--- + +## Always ask if not already covered + +Highest-value fields; source docs and web search usually lack them. Don't close an interview without them: + +1. **Qualified/active user definition** — applied on almost every agent question. +2. **Authority** — who owns the schema and whose conventions to follow. Prevents the agent copying a random user's messy style. +3. **North star, scoped to Mixpanel** — anchored to events that exist here, with any out-of-Mixpanel true north star noted separately. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/SKILL.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/SKILL.md new file mode 100644 index 0000000..f732540 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/SKILL.md @@ -0,0 +1,143 @@ +--- +name: mixpanel-ai-readiness +license: Apache-2.0 +description: > + Set up everything Mixpanel's AI assistants need to work well on a customer's + data: business context (org and project level) AND Lexicon metadata (event + descriptions, property descriptions, tags) that lets the agent understand the + data itself. Use whenever a user wants to get a project or org "ready for the + AI / agent / MCP", set up business context for the first time, import context + written down elsewhere, fill gaps, or check how AI-ready a project is across + the business and data layers. Also use on phrasings like — "set us up for + Mixpanel AI", "the agent keeps asking what our events mean", "make our project + agent-ready", "we have this in Notion, can you pull it in", "how ready are we + for the agent". Owns the business-context layer directly; delegates + event/property/tag enrichment to the manage-lexicon skill. Do NOT use for: + building dashboards; metric investigations; deleting data. Requires Mixpanel + MCP. Works best with manage-lexicon available. +--- + +# Mixpanel AI Readiness + +This skill gets a customer's Mixpanel setup ready for AI assistants (the in-product agent and MCP clients). "Ready" means two layers are in place: + +1. **Business context** — markdown the agent reads first, at org level (who the company is) and project level (how a project is set up). The agent uses it to know the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** +2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has to guess what each event and property means on every query. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. + +The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. + +--- + +# Critical constraints (read before any write) + +Properties of the underlying APIs, not preferences. + +1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. The skill MUST read existing context, merge in memory, show a full diff, and require `CONFIRM` before every write. Never write a partial document. +2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. +3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. +4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. +5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. +6. **Delegate Lexicon work; don't duplicate it.** Event/property/tag enrichment runs through `manage-lexicon`. If that skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. + +--- + +# Components + +## Canonical commands + +Loaded on demand from `commands/`. + +| Command | File | Match if message contains any of | +|---|---|---| +| `status` | `commands/status.md` | how ready, ai-ready, score, audit, what's missing, check our setup | +| `import-context` | `commands/import-context.md` | import, we already have, pull from, from notion/doc/drive, paste | +| `setup-context` | `commands/setup-context.md` | set up context, configure context, interview, create context | +| `enrich-data` | `commands/enrich-data.md` | event descriptions, property descriptions, tags, clean up events, lexicon | +| `target` | `commands/target.md` | switch level, org vs project, change target, where should this live | + +If a message matches more than one, show the Command menu. The natural full-onboarding path is: `status` → `import-context` (or `setup-context`) → `enrich-data` → `status`. + +## Command menu + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + Mixpanel AI Readiness — [Org Name] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + Business context layer + 1. Status — Score readiness across BOTH layers + 2. Import context — Pull context you already have (connector or file) + 3. Setup context — Interview to build context from scratch + 4. Target — Org level, project level, or both + Data layer (Lexicon) + 5. Enrich data — Event/property descriptions + tags (via manage-lexicon) + 6. Exit +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## Session vocabulary + +| Key | Shape | Description | +|---|---|---| +| `org_id`, `org_name` | string | Active organization. | +| `target_level` | `"org"`\|`"project"`\|`"both"` | Where context is written. | +| `project_id`, `project_name` | string | Active project, when in scope. | +| `caller_role` | map | Resolved role at org and project — the permission gate. | +| `existing_context` | map | `{ org, project }` current context, read before any write. | +| `imported_source` | map | Raw text pulled from a connector/file, plus its origin, pre-mapping. | +| `schema_facts` | map | Derived top events/properties, integrations, timezone. Timestamped. | +| `interview_answers` | map | Section-keyed answers, for gaps not covered by import. | +| `draft_context` | map | `{ org, project }` composed markdown pending preview/confirm. | +| `lexicon_score` | map | Coverage summary returned from `manage-lexicon` (for the unified status). | + +## Behaviour rules + +1. **No phase narration.** Output questions, previews, diffs, confirmation prompts, errors, results. Not "I'll now read your doc…". +2. **Import before interview.** Always offer to pull existing context first. Interview is the gap-filler, not the default. +3. **Read before write, always.** Populate `existing_context` for the target before composing. The diff is computed against it. +4. **Preview + diff before every context write.** Show the full proposed document and what changes vs current. Require literal `CONFIRM`. `EXPORT` saves a local `.md` without writing. Anything else cancels. +5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT`. +6. **Never overwrite populated content silently.** Existing sections are preserved and shown; the user chooses per section. +7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. +8. **Ground everything.** Only what import or interview or `schema_facts` support. Uncertainty → Open Questions, never hedged prose. +9. **Quarantine volatile facts.** Schema counts/lists go only in the fenced, timestamped Schema Snapshot section. +10. **Delegate Lexicon, surface its result.** `enrich-data` hands off to `manage-lexicon` and captures `lexicon_score` so `status` can report both layers. +11. **Audit trail.** After every successful write, append `ai-readiness-runs/[ISO-timestamp]-[command].json` with org/target/project, command, sections or entities written, counts. +12. **`exit` always valid.** + +--- + +# Execution + +## 1. Resolve organization and target +Identify the org. Determine `target_level` (infer from the request, else ask: org / project / both). Resolve `project_id` if project is in scope. If Mixpanel MCP is unavailable, tell the user to connect it and stop. + +## 2. Permission pre-check +Resolve `caller_role` for each target. Surface any level the user can't edit up front; adjust target or offer `EXPORT`. + +## 3. Read existing context +Read current context for each target into `existing_context`. Mandatory — diffs and merges compute against it. + +## 3.5. Offer import-context first (if context is empty or thin) +**BEFORE setup-context or the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): + +**Always ask first:** +``` +Your [org/project] context is currently [empty/minimal]. + +Do you have existing business context written down somewhere? + • Notion, Google Drive, Confluence, or other connected source + • A file or text block you can paste + • Or I can interview you from scratch + +Where should I look? (or type 'interview' to skip import) +``` + +Only proceed to `setup-context` or the menu if the user explicitly declines to import or types "interview" / "skip" / "scratch". This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule). + +## 4. Command loop +Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry, return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). + +## Reference files +- `references/context-template.md` — fixed org and project section templates (who/what/where/why/how), aligned to Mixpanel's native context generation so output is consistent with the in-product "Generate with AI" button. +- `references/interview-questions.md` — question bank per section, including the authority question. +- `references/import-mapping.md` — how to map an arbitrary source doc onto the template, what to keep, what to drop. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/enrich-data.md new file mode 100644 index 0000000..4b107fb --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/enrich-data.md @@ -0,0 +1,31 @@ +# Command: enrich-data + +Set up the Lexicon metadata the agent needs to understand the data itself: event descriptions, property descriptions, and tags. This command **delegates to the `manage-lexicon` skill** run inline — it does not reimplement enrichment. Its job is to hand off cleanly and capture the result for the unified readiness status. + +**Session reads:** `org_id`, `project_id`, `project_name`, `caller_role` +**Session writes:** `lexicon_score` + +--- + +## Step 1 — Preconditions + +- A project must be in scope (`project_id`). If only org-level context was being worked on, ask which project to enrich — Lexicon is per-project. +- The caller needs project owner/admin to write Lexicon. Check `caller_role`; if missing, say so and offer to have an admin run this step. +- Confirm `manage-lexicon` is available. If it is not, tell the user the data layer can't be set up automatically right now, point them to the `manage-lexicon` skill in the Mixpanel skills repository, and return — do **not** reimplement event/property/tag editing here. + +## Step 2 — Hand off to manage-lexicon + +Invoke `manage-lexicon` for this `project_id`. Drive it through, in order: + +1. **`score-lexicon`** — get the current metadata health (description coverage on events and properties, tag coverage). Capture the score. +2. **`enrich-and-tag`** — fill empty event descriptions, empty property descriptions, and add tags. Respect that skill's own rules: fill-only-empty (never overwrite existing metadata), add tags rather than replace, and its preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. + +Let `manage-lexicon` own its previews and confirmations. This command does not duplicate or wrap those prompts; the user interacts with manage-lexicon's flow directly. + +## Step 3 — Capture result + +After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise run `score-lexicon` once more to capture the after state. + +## Follow-on + +Offer: "Want me to re-run **status** so you can see the full AI-readiness picture across context and data?" → hands to `status`. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/import-context.md new file mode 100644 index 0000000..dc72da2 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/import-context.md @@ -0,0 +1,60 @@ +# Command: import-context + +Pull business knowledge the customer has already written down, map it onto the fixed template, show what mapped and what's still empty, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. + +**Session reads:** `org_id`, `target_level`, `project_id`, `caller_role`, `existing_context`, `schema_facts` +**Session writes:** `imported_source`, `interview_answers` (for gaps), `draft_context` + +--- + +## Step 1 — Find the source + +Ask where the existing context lives, and accept any of: + +- **A connected MCP connector** — e.g. Notion, Google Drive, Confluence, a wiki, a knowledge source. Search it for the relevant doc (tracking plan, data dictionary, analytics README, PRD, "about our metrics" page). If several connectors are connected, ask which to search, or search the most likely and confirm the hit. +- **A pasted block or uploaded file** — the user drops text or a file directly. + +Do not assume which connector. Detect what's connected; if nothing relevant is, fall back to paste/file. If the user names a connector that isn't connected, tell them and offer paste/file or `setup-context` instead. + +Store the raw retrieved text and its origin in `imported_source`. Never write this raw text to Mixpanel — it is input, not output. + +## Step 2 — Map onto the template + +Using `references/import-mapping.md`, map the source onto `references/context-template.md` for the target level(s): + +- Pull each template section's content from the source where it exists. +- **Drop** what doesn't belong: meeting notes, roadmap, changelogs, anything time-bound or operational that isn't durable context. +- Do not invent. If a section has no source material, leave it empty and mark it for the gap step. +- Schema-derived facts still come from `schema_facts` (Step via setup-context's schema pull), not from the doc — the doc's own numbers are likely stale. + +## Step 3 — Show the mapping + +Present a coverage view so the user sees exactly what the import produced: + +``` +Mapped from [source]: + ✓ Business / domain ← from doc + ✓ North star ← from doc + ✓ Vocabulary & acronyms ← from doc + ⚠ Qualified-user definition — partial, needs confirmation + ✗ Authority & governance — not found in source + ✗ Key dashboards — not found in source +``` + +Anything ✗ or ⚠ is a gap. + +## Step 4 — Fill gaps (mini-interview) + +For gaps only, ask the targeted questions from `references/interview-questions.md`. Always include the **authority** question and the **qualified-user** question if the import didn't cover them — these are the highest-value fields and source docs usually lack them. Record in `interview_answers`. Unknowns → Open Questions. + +## Step 5 — Compose, preview, diff, confirm + +Identical to `setup-context` Steps 3–4: compose `draft_context` to the template (durable content first, schema facts fenced + timestamped, uncertainty in Open Questions), respect the 50k cap, show the full document plus a diff against `existing_context`. Only literal `CONFIRM` proceeds to write. `EXPORT` saves a local `.md`. For `both`, confirm each level separately. + +## Step 6 — Back up, then write + +Back up existing context per SKILL.md's "Back up before every write" rule, then write the composed document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +## Follow-on + +After writing: "Want me to **enrich the data layer** (event/property descriptions and tags) so the agent understands your schema too? I'll run that through manage-lexicon." → hands to `enrich-data`. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/setup-context.md new file mode 100644 index 0000000..05a318a --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/setup-context.md @@ -0,0 +1,71 @@ +# Command: setup-context + +Build business context from scratch via a guided interview, when the customer has nothing written down to import. Pulls schema facts first to make questions concrete, drafts to the fixed template, previews with a diff, and writes on `CONFIRM`. Handles org level, project level, or both. + +**Session reads:** `org_id`, `target_level`, `project_id`, `project_name`, `caller_role`, `existing_context` +**Session writes:** `schema_facts`, `interview_answers`, `draft_context` + +> **CRITICAL:** If the customer *does* have existing context somewhere, prefer `import-context` and use this only to fill gaps. **Always offer import first** before starting this command. See SKILL.md's "Offer import-context first" step. + +--- + +## Step 0 — Confirm the user wants interview-based setup + +**ALWAYS ask this first** (unless they explicitly invoked "setup-context" or typed "interview"): + +``` +Do you have existing business context written down somewhere I could pull from? + • Notion, Confluence, Google Drive, wiki, tracking plan, etc. + • Or paste/upload a file + +If yes, we'll use import-context instead (faster and more complete). +If no, I'll interview you from scratch. + +Which would you prefer? +``` + +If they have a source, hand off to `import-context` immediately. Only proceed with this command if they confirm they have nothing to import. + +## Step 1 — Research and pull schema first + +Before asking the user anything (per `references/interview-questions.md`): +- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. +- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped. Counts never go into prose, only the fenced Schema Snapshot. Partial failure: continue, note the gap in Open Questions. + +## Step 2 — Interview (gaps and internal-only facts) + +Work `references/interview-questions.md`, in small batches, seeded with research and `schema_facts`. Present the web-researched Business/Segments drafts for correction rather than asking from scratch. + +Mandatory, do not skip: +- **North star, scoped to Mixpanel**: which *Mixpanel-trackable* metric best reflects success, anchored to real events. Capture any true north star that lives outside Mixpanel (revenue, NRR, GMV) separately, with the closest in-Mixpanel proxy, so the agent doesn't chase data that isn't here. +- **Qualified/active user definition** in this data. +- **Authority**: who owns the schema and canonical reports, whose conventions the agent should follow, when to defer to a human vs. create new entities. Highest-value field. +- **Vocabulary**: ask first whether a glossary/data dictionary exists and import it; only interview term-by-term if there's no source. + +Record in `interview_answers`. Unknowns → Open Questions, never guessed. + +## Step 3 — Compose draft + +Fill `references/context-template.md`: durable `tldr;` first (what/where/when/who/how/why, 1–3 sentences each, linking deeper); qualitative sections from answers; all schema facts in the fenced, timestamped Schema Snapshot; unsupported items in Open Questions. Respect the 50k cap (trim Schema Snapshot first). + +## Step 4 — Preview, diff, confirm + +Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged) — required because writes are full-replace. Prompt: + +``` +Write this to [org / project: NAME] business context? + CONFIRM — commit this exact document (replaces current context at this level) + EXPORT — save draft to a local .md file, don't write to Mixpanel + edit — tell me what to change + exit — discard +``` + +Only literal `CONFIRM` commits. For `both`, confirm each level separately. + +## Step 5 — Back up, then write + +Back up existing context per SKILL.md's "Back up before every write" rule, then write the full document for the level. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +## Follow-on + +"Now set up the **data layer** (event/property descriptions + tags via manage-lexicon) so the agent understands your schema?" → hands to `enrich-data`. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/status.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/status.md new file mode 100644 index 0000000..f548706 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/status.md @@ -0,0 +1,48 @@ +# Command: status + +The unified AI-readiness readout. Scores both layers in one view — business context completeness *and* Lexicon coverage — and tells the user exactly what's missing and which command fixes it. This is the re-engagement hook: run it on any account to see where it stands and what to do next. It is read-only. + +**Session reads:** `org_id`, `org_name`, `target_level`, `project_id`, `project_name`, `existing_context`, `lexicon_score` +**Session writes:** `existing_context`, `lexicon_score` (refreshes both) + +--- + +## Step 1 — Business-context layer + +For the org and (if a project is in scope) the project: + +- Read current context if not already in `existing_context`. +- Score completeness against `references/context-template.md`: which required sections are present and non-empty. Weight the high-value sections (north star, qualified-user definition, authority & governance) more heavily — a doc with vocabulary but no authority section is weaker than the raw section count suggests. +- Flag staleness: if a Schema Snapshot section exists, compare its timestamp to now and warn if old. + +## Step 2 — Data layer (Lexicon) + +If a project is in scope and `manage-lexicon` is available, run its `score-lexicon` (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. + +## Step 3 — Present one readout + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + AI Readiness — [Project Name] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + BUSINESS CONTEXT + Org level ●●●●○ present, missing: customer segments + Project level ●●○○○ thin — no authority section, no qualified-user def + + DATA (LEXICON) + Event descriptions 45% + Property descriptions 30% + Events tagged 12% + + TOP GAPS (most impact first) + 1. Project authority & governance → import-context / setup-context + 2. Property descriptions (30%) → enrich-data + 3. Event tags (12%) → enrich-data +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +Order gaps by impact on agent quality, not by raw percentage: a missing authority section or qualified-user definition hurts the agent more than a few undescribed low-volume events. Each gap names the command that fixes it. + +## Follow-on + +Offer the single highest-impact next step as a direct handoff (e.g. "Start with **import-context** for the project — want me to go?"). Don't dump the whole menu; recommend the one move. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/target.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/target.md new file mode 100644 index 0000000..ec6ba68 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/target.md @@ -0,0 +1,37 @@ +# Command: target + +Change which level(s) the skill writes business context to: org-level, project-level, or both. + +**Session reads:** `org_id`, `org_name`, `project_id`, `project_name`, `caller_role` +**Session writes:** `target_level` + +--- + +## Prompt + +Ask which level the user wants to target: + +``` +Where should business context live? + 1. Org level only — shared across all projects + 2. Project level only — scoped to [Project Name] + 3. Both — org context + project-specific context +``` + +## Validate permissions + +Check `caller_role` for the chosen target(s). If the user lacks write permission for a level, surface it and offer alternatives: + +- If they can't write to org: "You need org owner/admin to write org-level context. Want to target project only?" +- If they can't write to project: "You need project owner/admin to write project context. Want to target org only, or export locally?" + +## Set and confirm + +Update `target_level` to `"org"`, `"project"`, or `"both"`. Confirm back to the user: "Got it — targeting [level(s)]." + +## Follow-on + +Offer the next natural step based on where they are in the workflow: +- If they haven't run `status` yet: "Want me to check your AI readiness **status** first?" +- If they have context to import: "Ready to **import** your existing context?" +- Otherwise: "Ready to **set up** context from scratch?" diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/context-template.md new file mode 100644 index 0000000..af5cfc0 --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/context-template.md @@ -0,0 +1,89 @@ +# Context Template + +Fixed section structure for generated context. Adapted from the who/what/where/why/how framework Mixpanel uses for native context generation, so skill output stays consistent with the in-product "Generate with AI" button. **Structure is fixed; only content varies.** Used by `import-context`, `setup-context`, and scored by `status`. + +--- + +## ORG-LEVEL TEMPLATE + +```markdown +# [Company] — Organization Context + +## tldr; +- **What**: One line — what the company does and its business model. +- **Who**: One line — primary customer segments and who uses Mixpanel internally. +- **How we measure success**: One line — the Mixpanel-trackable metric that best reflects success, plus any true north star that lives outside Mixpanel. + +## Business +[2–4 sentences: product, business model, how the company makes money. Durable facts only.] + +## North Star & Key Metrics +- **North star (in Mixpanel)**: [the Mixpanel-trackable metric that best reflects success + why] +- **Supporting metrics (in Mixpanel)**: [list] +- **True north star outside Mixpanel**: [e.g. revenue/NRR/GMV in another tool, + closest Mixpanel proxy — or "none, north star is trackable here"] +- **Definition of a qualified/active user**: [the exact rule the agent should apply] + +## Customer Segments +[Named segments and what distinguishes them.] + +## Internal Vocabulary & Acronyms +[Term — meaning. Anything the agent would otherwise misread.] + +## Open Questions +[Anything not yet known, phrased as questions. Never fabricate.] +``` + +--- + +## PROJECT-LEVEL TEMPLATE + +```markdown +# [Project] — Project Context + +## tldr; +- **What**: One line — what this project tracks and for which product/surface. +- **Where**: One line — where data comes from (SDK, server, warehouse) and key integrations. +- **Who**: One line — who has authority over this project's schema and reports. +- **How**: One line — how analysis is done here (custom entities, conventions). +- **Why**: One line — the business decisions this project's analysis feeds. + +## Domain & Vocabulary +[What the product is, what the events represent, who the tracked end-user is.] + +## Event Taxonomy & Naming Conventions +[How events/properties are named and organized. Casing, prefixes, the canonical +patterns the agent should follow when referring to or creating entities.] + +## Authority & Governance +[Who owns the schema and canonical reports. Whose conventions to emulate. When +the agent should defer to a human instead of creating new entities. This section +prevents the agent from copying a non-authoritative user's chaotic style.] + +## Key Dashboards & Reports +[Named canonical surfaces and what each is for.] + +## Definition of Active/Qualified User (this project) +[If it differs from org level.] + +## Schema Snapshot + +``` +Top events: [list] +Key properties: [list] +Integrations in use: [list] +Timezone: [tz] +``` + +## Open Questions +[Anything not grounded in answers, import, or schema, phrased as questions.] +``` + +--- + +## Rules + +- `tldr;` H3s are 1–3 sentences each. Terse. Point to deeper sections, don't duplicate. +- Schema-derived facts live **only** in Schema Snapshot, fenced and timestamped. +- No quantity-in-prose ("project has 26 users") — goes stale, is bloat. +- Hedging language not allowed in the body. Uncertainty → Open Questions. +- Imported content is mapped here section-by-section; it never enters raw. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/import-mapping.md new file mode 100644 index 0000000..8db094d --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/import-mapping.md @@ -0,0 +1,32 @@ +# Import Mapping + +How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template. Never paste raw source into Mixpanel. + +## Mapping table (source → template section) + +| If the source has… | Map to | +|---|---| +| "About us", company overview, what we do/sell | Business / Domain & Vocabulary | +| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | +| Definition of active/qualified/engaged user, MAU/WAU logic | Definition of Qualified User | +| Customer types, segments, personas, tiers | Customer Segments | +| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | +| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | +| Data owner, schema owner, "ask X before adding events", RACI | Authority & Governance | +| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | +| Default project guidance, which project for what | Conventions & Defaults (org) | + +## What to drop (do not map) + +- Meeting notes, decisions logs, dated standups. +- Roadmap, upcoming features, "Q3 plans" — time-bound, not durable context. +- Changelogs, migration notes, ticket references. +- Anything that contradicts the live schema — flag it as an Open Question rather than importing it. +- Raw numbers/counts — schema facts come from the live pull, fenced and timestamped, not from the doc. + +## Rules + +- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. +- **Preserve the customer's own vocabulary.** If they call it "design partners" not "enterprise customers", keep their term — the agent should speak their language. +- **Attribute nothing you can't ground.** If the doc implies an owner but doesn't name one, that's an Open Question, not an Authority entry. +- **Show your work.** The coverage view (import-context Step 3) must make clear which sections came from the source and which are still empty, so the user trusts the result and knows what the gap-interview will cover. diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/interview-questions.md new file mode 100644 index 0000000..c30872d --- /dev/null +++ b/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/interview-questions.md @@ -0,0 +1,73 @@ +# Interview Questions + +Starter question bank, grouped by template section. **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` where noted, ask in small batches. Unknown answers → Open Questions, never guessed. + +--- + +## Before interviewing — research and pre-fill + +Do these first, so the interview is mostly confirmation, not blank-filling: + +1. **Web search the company.** What it does, business model, customers/segments. Draft the **Business** and **Customer Segments** sections from public sources, then present for correction (see below). Don't ask these cold. +2. **Pull the schema** into `schema_facts` (top events, key properties) — needed to anchor the north-star and event questions to what actually exists in Mixpanel. +3. **Check for a definitions source.** Before asking vocab questions, ask if one exists and import it instead. + +--- + +## ORG LEVEL + +### Business *(pre-filled from web search — confirm, don't ask)* +- Here's what I found about the company: [drafted summary]. Is this right? Anything to fix or add? +- Anything about the business model or how you make money that the public description gets wrong? + +### Customer Segments *(pre-filled from web search — confirm, don't ask)* +- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? + +### North Star & Key Metrics *(must be Mixpanel-trackable)* +- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[Verified] Query Run`, activations, something else?") +- What are the 2–3 supporting metrics **in Mixpanel** underneath it? +- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR, GMV in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. +- How do you define an "active" or "qualified" user in this data? (the exact rule) + +### Vocabulary & Acronyms *(ask for a source first)* +- Do you have a glossary, data dictionary, or definitions page anywhere? If so, point me to it and I'll pull from it. +- If not: what internal terms or acronyms would the agent misread? Term + meaning. (focus on words that mean something specific in *your* data — "activation", "engaged", "churned") + +--- + +## PROJECT LEVEL + +### Domain & Vocabulary +- What product or surface does this project track? (web app, mobile, backend, a specific feature) +- Who is the end-user whose behavior shows up here? (your customer, an internal team, a machine/service) +- *(Seed with schema_facts)* Your highest-volume events are `[X]` and `[Y]` — one line each, what do those represent? + +### Event Taxonomy & Naming Conventions +- How are events named here? Casing or prefix rules? (e.g. "Verb Noun", `[Verified]` prefix, snake_case) +- *(Seed with schema_facts)* I see properties like `[A]` and `[B]` — what do they mean, and which matter most for analysis? +- Any events or properties that look important but should be ignored? (test, deprecated, internal-only) + +### Authority & Governance +- Who owns the schema and the canonical reports in this project? +- Whose naming and conventions should the agent follow when unsure? +- When should the agent stop and ask a human instead of creating a new event, property, or report itself? + +### Key Dashboards & Reports +- Which dashboards/reports are the canonical, trusted ones? What is each for? +- Where would you point a new team member first? + +### Qualified User (this project) +- Does "active" or "qualified" user mean something different here than at the org level? If so, what? + +### Why / Business Impact +- What decisions does this project's analysis actually drive, and who acts on them? + +--- + +## Always ask if not already covered + +Highest-value fields; source docs and web search usually lack them. Don't close an interview without them: + +1. **Qualified/active user definition** — applied on almost every agent question. +2. **Authority** — who owns the schema and whose conventions to follow. Prevents the agent copying a random user's messy style. +3. **North star, scoped to Mixpanel** — anchored to events that exist here, with any out-of-Mixpanel true north star noted separately. From 208ba08d54445fe4210a6563f6f92479c07ac0f2 Mon Sep 17 00:00:00 2001 From: Yonah Dorfman Date: Mon, 13 Jul 2026 11:25:44 +0300 Subject: [PATCH 2/3] changes after ai skill review --- .../{mixpanel-ai-readiness => prepare-ai-readiness}/SKILL.md | 0 .../commands/enrich-data.md | 0 .../commands/import-context.md | 0 .../commands/setup-context.md | 0 .../commands/status.md | 0 .../commands/target.md | 0 .../references/context-template.md | 0 .../references/import-mapping.md | 0 .../references/interview-questions.md | 0 .../{mixpanel-ai-readiness => prepare-ai-readiness}/SKILL.md | 0 .../commands/enrich-data.md | 0 .../commands/import-context.md | 0 .../commands/setup-context.md | 0 .../commands/status.md | 0 .../commands/target.md | 0 .../references/context-template.md | 0 .../references/import-mapping.md | 0 .../references/interview-questions.md | 0 .../{mixpanel-ai-readiness => prepare-ai-readiness}/SKILL.md | 0 .../commands/enrich-data.md | 0 .../commands/import-context.md | 0 .../commands/setup-context.md | 0 .../commands/status.md | 0 .../commands/target.md | 0 .../references/context-template.md | 0 .../references/import-mapping.md | 0 .../references/interview-questions.md | 0 27 files changed, 0 insertions(+), 0 deletions(-) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/SKILL.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/enrich-data.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/import-context.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/setup-context.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/status.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/target.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/context-template.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/import-mapping.md (100%) rename plugins/mixpanel-mcp-eu/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/interview-questions.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/SKILL.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/enrich-data.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/import-context.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/setup-context.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/status.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/target.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/context-template.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/import-mapping.md (100%) rename plugins/mixpanel-mcp-in/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/interview-questions.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/SKILL.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/enrich-data.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/import-context.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/setup-context.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/status.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/commands/target.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/context-template.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/import-mapping.md (100%) rename plugins/mixpanel-mcp/skills/{mixpanel-ai-readiness => prepare-ai-readiness}/references/interview-questions.md (100%) diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/SKILL.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/SKILL.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/SKILL.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/SKILL.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/enrich-data.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/enrich-data.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/enrich-data.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/import-context.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/import-context.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/import-context.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/setup-context.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/setup-context.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/setup-context.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/status.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/status.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/status.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/status.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/target.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/target.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/commands/target.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/target.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/context-template.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/context-template.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/context-template.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/import-mapping.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/import-mapping.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/import-mapping.md diff --git a/plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/interview-questions.md similarity index 100% rename from plugins/mixpanel-mcp-eu/skills/mixpanel-ai-readiness/references/interview-questions.md rename to plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/interview-questions.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/SKILL.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/SKILL.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/SKILL.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/SKILL.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/enrich-data.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/enrich-data.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/enrich-data.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/import-context.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/import-context.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/import-context.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/setup-context.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/setup-context.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/setup-context.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/status.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/status.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/status.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/status.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/target.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/target.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/commands/target.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/target.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/context-template.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/context-template.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/context-template.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/import-mapping.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/import-mapping.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/import-mapping.md diff --git a/plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/interview-questions.md similarity index 100% rename from plugins/mixpanel-mcp-in/skills/mixpanel-ai-readiness/references/interview-questions.md rename to plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/interview-questions.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/SKILL.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/SKILL.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/SKILL.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/SKILL.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/enrich-data.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/enrich-data.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/enrich-data.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/import-context.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/import-context.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/import-context.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/setup-context.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/setup-context.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/setup-context.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/status.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/status.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/status.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/status.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/target.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/target.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/commands/target.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/target.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/context-template.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/context-template.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/context-template.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/import-mapping.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/import-mapping.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/import-mapping.md diff --git a/plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/interview-questions.md similarity index 100% rename from plugins/mixpanel-mcp/skills/mixpanel-ai-readiness/references/interview-questions.md rename to plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/interview-questions.md From 10459683847e631d398d36f4cc200cdd59f08cdd Mon Sep 17 00:00:00 2001 From: Yonah Dorfman Date: Tue, 21 Jul 2026 15:30:47 +0300 Subject: [PATCH 3/3] changes from July 21 2026 with skill at 98.8% readiness and small change is something I disagree with --- .../skills/prepare-ai-readiness/SKILL.md | 83 ++++++++++--------- .../commands/enrich-data.md | 11 +-- .../commands/import-context.md | 32 ++++--- .../commands/setup-context.md | 49 ++--------- .../prepare-ai-readiness/commands/status.md | 2 +- .../prepare-ai-readiness/commands/target.md | 6 +- .../references/context-template.md | 58 ++++++++++--- .../references/import-mapping.md | 42 ++++++---- .../references/interview-questions.md | 48 ++++++----- .../skills/prepare-ai-readiness/SKILL.md | 83 ++++++++++--------- .../commands/enrich-data.md | 11 +-- .../commands/import-context.md | 32 ++++--- .../commands/setup-context.md | 49 ++--------- .../prepare-ai-readiness/commands/status.md | 2 +- .../prepare-ai-readiness/commands/target.md | 6 +- .../references/context-template.md | 58 ++++++++++--- .../references/import-mapping.md | 42 ++++++---- .../references/interview-questions.md | 48 ++++++----- .../skills/prepare-ai-readiness/SKILL.md | 83 ++++++++++--------- .../commands/enrich-data.md | 11 +-- .../commands/import-context.md | 32 ++++--- .../commands/setup-context.md | 49 ++--------- .../prepare-ai-readiness/commands/status.md | 2 +- .../prepare-ai-readiness/commands/target.md | 6 +- .../references/context-template.md | 58 ++++++++++--- .../references/import-mapping.md | 42 ++++++---- .../references/interview-questions.md | 48 ++++++----- 27 files changed, 537 insertions(+), 456 deletions(-) diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/SKILL.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/SKILL.md index f732540..9749887 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/SKILL.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/SKILL.md @@ -1,43 +1,23 @@ --- -name: mixpanel-ai-readiness +name: prepare-ai-readiness license: Apache-2.0 description: > - Set up everything Mixpanel's AI assistants need to work well on a customer's - data: business context (org and project level) AND Lexicon metadata (event - descriptions, property descriptions, tags) that lets the agent understand the - data itself. Use whenever a user wants to get a project or org "ready for the - AI / agent / MCP", set up business context for the first time, import context - written down elsewhere, fill gaps, or check how AI-ready a project is across - the business and data layers. Also use on phrasings like — "set us up for - Mixpanel AI", "the agent keeps asking what our events mean", "make our project - agent-ready", "we have this in Notion, can you pull it in", "how ready are we - for the agent". Owns the business-context layer directly; delegates - event/property/tag enrichment to the manage-lexicon skill. Do NOT use for: - building dashboards; metric investigations; deleting data. Requires Mixpanel - MCP. Works best with manage-lexicon available. + Gets a Mixpanel org or project ready for its AI assistants — business context + and Lexicon metadata. Use to set up or import context, fill gaps, or check + AI-readiness: "set us up for Mixpanel AI", "how ready are we for the agent". + Not for dashboards or metrics. Requires Mixpanel MCP. --- # Mixpanel AI Readiness This skill gets a customer's Mixpanel setup ready for AI assistants (the in-product agent and MCP clients). "Ready" means two layers are in place: -1. **Business context** — markdown the agent reads first, at org level (who the company is) and project level (how a project is set up). The agent uses it to know the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** -2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has to guess what each event and property means on every query. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. +1. **Business context** — markdown designed to be the agent's first read, at org level (who the company is) and project level (how a project is set up), so it can ground the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** +2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has less signal for what each event and property means. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. -The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. - ---- - -# Critical constraints (read before any write) - -Properties of the underlying APIs, not preferences. +How the agent consumes each layer evolves with the product — verify current agent behavior against Mixpanel docs. -1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. The skill MUST read existing context, merge in memory, show a full diff, and require `CONFIRM` before every write. Never write a partial document. -2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. -3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. -4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. -5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. -6. **Delegate Lexicon work; don't duplicate it.** Event/property/tag enrichment runs through `manage-lexicon`. If that skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. +The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. --- @@ -94,15 +74,44 @@ If a message matches more than one, show the Command menu. The natural full-onbo 1. **No phase narration.** Output questions, previews, diffs, confirmation prompts, errors, results. Not "I'll now read your doc…". 2. **Import before interview.** Always offer to pull existing context first. Interview is the gap-filler, not the default. 3. **Read before write, always.** Populate `existing_context` for the target before composing. The diff is computed against it. -4. **Preview + diff before every context write.** Show the full proposed document and what changes vs current. Require literal `CONFIRM`. `EXPORT` saves a local `.md` without writing. Anything else cancels. -5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT`. +4. **Preview + diff before every context write.** Never write without showing the full proposed document, a diff against `existing_context`, and getting explicit confirmation. +5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT` (saves the draft to a local file instead of writing to Mixpanel — see Write flow below). 6. **Never overwrite populated content silently.** Existing sections are preserved and shown; the user chooses per section. -7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. +7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. If no local file-write capability is available (or it's denied), don't write or fail silently: print the full existing document inline so the user can save it themselves, and get explicit confirmation to proceed without a file backup. 8. **Ground everything.** Only what import or interview or `schema_facts` support. Uncertainty → Open Questions, never hedged prose. 9. **Quarantine volatile facts.** Schema counts/lists go only in the fenced, timestamped Schema Snapshot section. 10. **Delegate Lexicon, surface its result.** `enrich-data` hands off to `manage-lexicon` and captures `lexicon_score` so `status` can report both layers. 11. **Audit trail.** After every successful write, append `ai-readiness-runs/[ISO-timestamp]-[command].json` with org/target/project, command, sections or entities written, counts. 12. **`exit` always valid.** +13. **Resolve identifiers by name or ID.** Accept org/project by human-readable name or system ID. Match by ID first, then by case-insensitive name; if a name matches more than one, list the matches and ask which. + +## Write flow + +The shared tail of `setup-context` and `import-context`, and the canonical definition of the composition rules, confirmation prompt, and write sequence. Each command sources `draft_context` its own way (from interview answers, or from mapped source), but composes it by the same rules: fill `references/context-template.md` with the durable `tldr;` first; schema facts from `schema_facts` only in the fenced, timestamped Schema Snapshot; anything unsupported in Open Questions (per the "Ground everything" rule); respect the 50,000-char cap per context level (see Critical constraints below), trimming the Schema Snapshot first. From the composed draft, both do exactly this: + +1. **Preview, diff, confirm.** Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged). For `both`, show both levels together. Prompt: + ``` + Write this to [org / project: NAME / both] business context? + CONFIRM — commit this exact document (replaces current context at that level) + EXPORT — save draft to a local .md file, don't write to Mixpanel + edit — tell me what to change + exit — discard + ``` + Only literal `CONFIRM` commits; for `both`, one `CONFIRM` applies both levels (writes run per level; report each). `edit` scopes to the level named. Anything else cancels. +2. **Back up, then write.** Back up per the "Back up before every write" rule, then write the document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +--- + +# Critical constraints (read before any write) + +Properties of the underlying APIs, not preferences — every constraint below can change as Mixpanel's product evolves; verify current behavior, limits, and role requirements against Mixpanel docs before relying on the specifics. + +1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. Because of this, the skill MUST read existing context, merge in memory, and run the Write flow (full diff + `CONFIRM`) before every write. Never write a partial document. +2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. +3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. +4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. +5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. +6. **`manage-lexicon` can be unavailable.** Enrichment runs through it, per the "Delegate Lexicon, surface its result" behaviour rule. If the skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. --- @@ -115,10 +124,10 @@ Identify the org. Determine `target_level` (infer from the request, else ask: or Resolve `caller_role` for each target. Surface any level the user can't edit up front; adjust target or offer `EXPORT`. ## 3. Read existing context -Read current context for each target into `existing_context`. Mandatory — diffs and merges compute against it. +Populate `existing_context` for each target — mandatory before composing, per the "Read before write, always" rule. ## 3.5. Offer import-context first (if context is empty or thin) -**BEFORE setup-context or the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): +**BEFORE the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): **Always ask first:** ``` @@ -132,12 +141,12 @@ Do you have existing business context written down somewhere? Where should I look? (or type 'interview' to skip import) ``` -Only proceed to `setup-context` or the menu if the user explicitly declines to import or types "interview" / "skip" / "scratch". This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule). +Only proceed to `setup-context` or the menu if the user explicitly declines to import — types "interview" / "skip" / "scratch" — or explicitly invoked `setup-context` by name (asking to interview from scratch is itself a decline). This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule) without asking twice when the user already said which path they want. ## 4. Command loop -Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry, return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). +Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry if the command wrote anything (per the "Audit trail" rule — read-only commands like `status` skip it), return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). ## Reference files -- `references/context-template.md` — fixed org and project section templates (who/what/where/why/how), aligned to Mixpanel's native context generation so output is consistent with the in-product "Generate with AI" button. +- `references/context-template.md` — fixed org and project section templates, following a what/where/who/how/why framework at project level (org level uses a subset, plus default-project routing); that file carries the note on alignment with Mixpanel's native context generation. - `references/interview-questions.md` — question bank per section, including the authority question. - `references/import-mapping.md` — how to map an arbitrary source doc onto the template, what to keep, what to drop. diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/enrich-data.md index 4b107fb..1a4caf0 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/enrich-data.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/enrich-data.md @@ -10,21 +10,18 @@ Set up the Lexicon metadata the agent needs to understand the data itself: event ## Step 1 — Preconditions - A project must be in scope (`project_id`). If only org-level context was being worked on, ask which project to enrich — Lexicon is per-project. -- The caller needs project owner/admin to write Lexicon. Check `caller_role`; if missing, say so and offer to have an admin run this step. -- Confirm `manage-lexicon` is available. If it is not, tell the user the data layer can't be set up automatically right now, point them to the `manage-lexicon` skill in the Mixpanel skills repository, and return — do **not** reimplement event/property/tag editing here. +- The caller needs write permission for Lexicon (see SKILL.md's "Permissions gate writes" constraint for the role matrix). Check `caller_role`; if missing, name the required role and offer to have an admin run this step. +- Confirm `manage-lexicon` is available. If it is not, follow SKILL.md's "`manage-lexicon` can be unavailable" constraint — additionally, point the user to the `manage-lexicon` skill in the Mixpanel skills repository, then return. ## Step 2 — Hand off to manage-lexicon -Invoke `manage-lexicon` for this `project_id`. Drive it through, in order: - -1. **`score-lexicon`** — get the current metadata health (description coverage on events and properties, tag coverage). Capture the score. -2. **`enrich-and-tag`** — fill empty event descriptions, empty property descriptions, and add tags. Respect that skill's own rules: fill-only-empty (never overwrite existing metadata), add tags rather than replace, and its preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. +Hand this `project_id` to `manage-lexicon` and let it do two things, in this order: first measure current metadata health (description coverage on events and properties, tag coverage) and capture that score; then fill empty event and property descriptions and add tags — using whatever entry points that skill exposes. Respect its own guardrails (verify current behavior against that skill) — expect at least fill-only-empty (never overwrite existing metadata), add tags rather than replace, and a preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. Let `manage-lexicon` own its previews and confirmations. This command does not duplicate or wrap those prompts; the user interacts with manage-lexicon's flow directly. ## Step 3 — Capture result -After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise run `score-lexicon` once more to capture the after state. +After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise ask it to score coverage once more to capture the after state. ## Follow-on diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/import-context.md index dc72da2..fe2c319 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/import-context.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/import-context.md @@ -1,6 +1,6 @@ # Command: import-context -Pull business knowledge the customer has already written down, map it onto the fixed template, show what mapped and what's still empty, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. +Pull business knowledge the customer has already written down and turn it into template-conformant context, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. **Session reads:** `org_id`, `target_level`, `project_id`, `caller_role`, `existing_context`, `schema_facts` **Session writes:** `imported_source`, `interview_answers` (for gaps), `draft_context` @@ -16,16 +16,16 @@ Ask where the existing context lives, and accept any of: Do not assume which connector. Detect what's connected; if nothing relevant is, fall back to paste/file. If the user names a connector that isn't connected, tell them and offer paste/file or `setup-context` instead. -Store the raw retrieved text and its origin in `imported_source`. Never write this raw text to Mixpanel — it is input, not output. +Store the raw retrieved text and its origin in `imported_source` — never written to Mixpanel (see SKILL.md's "Imported content is mapped, never passed through raw" constraint). ## Step 2 — Map onto the template Using `references/import-mapping.md`, map the source onto `references/context-template.md` for the target level(s): - Pull each template section's content from the source where it exists. -- **Drop** what doesn't belong: meeting notes, roadmap, changelogs, anything time-bound or operational that isn't durable context. +- **Drop** what doesn't belong — see `references/import-mapping.md`'s "What to drop" list. - Do not invent. If a section has no source material, leave it empty and mark it for the gap step. -- Schema-derived facts still come from `schema_facts` (Step via setup-context's schema pull), not from the doc — the doc's own numbers are likely stale. +- Schema-derived facts still come from `schema_facts` (pulled during setup), not from the doc — the doc's own numbers are likely stale. ## Step 3 — Show the mapping @@ -33,27 +33,23 @@ Present a coverage view so the user sees exactly what the import produced: ``` Mapped from [source]: - ✓ Business / domain ← from doc - ✓ North star ← from doc - ✓ Vocabulary & acronyms ← from doc - ⚠ Qualified-user definition — partial, needs confirmation - ✗ Authority & governance — not found in source - ✗ Key dashboards — not found in source + ✓ Business ← from doc + ✓ North Star & Key Metrics ← from doc + ✓ Internal Vocabulary & Acronyms ← from doc + ⚠ Definition of Active/Qualified User (this project) — partial, needs confirmation + ✗ Authority & Governance — not found in source + ✗ Key Dashboards & Reports — not found in source ``` -Anything ✗ or ⚠ is a gap. +Use the literal template heading text for every row, per `references/import-mapping.md`'s verbatim-heading rule. Anything ✗ or ⚠ is a gap. ## Step 4 — Fill gaps (mini-interview) -For gaps only, ask the targeted questions from `references/interview-questions.md`. Always include the **authority** question and the **qualified-user** question if the import didn't cover them — these are the highest-value fields and source docs usually lack them. Record in `interview_answers`. Unknowns → Open Questions. +For gaps only, ask the targeted questions from `references/interview-questions.md`. Always cover that file's "Always ask if not already covered" mandatory list for anything the import didn't already fill. Record in `interview_answers` (unknowns → Open Questions per SKILL.md's "Ground everything" rule). -## Step 5 — Compose, preview, diff, confirm +## Step 5 — Compose and write -Identical to `setup-context` Steps 3–4: compose `draft_context` to the template (durable content first, schema facts fenced + timestamped, uncertainty in Open Questions), respect the 50k cap, show the full document plus a diff against `existing_context`. Only literal `CONFIRM` proceeds to write. `EXPORT` saves a local `.md`. For `both`, confirm each level separately. - -## Step 6 — Back up, then write - -Back up existing context per SKILL.md's "Back up before every write" rule, then write the composed document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. +Compose `draft_context` per SKILL.md's Write flow composition rules, with the mapped source material in its sections and gap answers from `interview_answers`. Then run SKILL.md's Write flow section. ## Follow-on diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/setup-context.md index 05a318a..b739641 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/setup-context.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/setup-context.md @@ -5,66 +5,31 @@ Build business context from scratch via a guided interview, when the customer ha **Session reads:** `org_id`, `target_level`, `project_id`, `project_name`, `caller_role`, `existing_context` **Session writes:** `schema_facts`, `interview_answers`, `draft_context` -> **CRITICAL:** If the customer *does* have existing context somewhere, prefer `import-context` and use this only to fill gaps. **Always offer import first** before starting this command. See SKILL.md's "Offer import-context first" step. - --- ## Step 0 — Confirm the user wants interview-based setup -**ALWAYS ask this first** (unless they explicitly invoked "setup-context" or typed "interview"): - -``` -Do you have existing business context written down somewhere I could pull from? - • Notion, Confluence, Google Drive, wiki, tracking plan, etc. - • Or paste/upload a file - -If yes, we'll use import-context instead (faster and more complete). -If no, I'll interview you from scratch. - -Which would you prefer? -``` - -If they have a source, hand off to `import-context` immediately. Only proceed with this command if they confirm they have nothing to import. +Run SKILL.md's "Offer import-context first" step. If they have a source, hand off to `import-context` immediately. Only proceed with this command if that step clears (per its own exemptions). ## Step 1 — Research and pull schema first Before asking the user anything (per `references/interview-questions.md`): -- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. -- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped. Counts never go into prose, only the fenced Schema Snapshot. Partial failure: continue, note the gap in Open Questions. +- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. If no web search tool is available, skip this pre-fill and ask those questions directly in Step 2 instead. +- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped, per SKILL.md's "Quarantine volatile facts" rule. Partial failure: continue, note the gap in Open Questions. ## Step 2 — Interview (gaps and internal-only facts) Work `references/interview-questions.md`, in small batches, seeded with research and `schema_facts`. Present the web-researched Business/Segments drafts for correction rather than asking from scratch. -Mandatory, do not skip: -- **North star, scoped to Mixpanel**: which *Mixpanel-trackable* metric best reflects success, anchored to real events. Capture any true north star that lives outside Mixpanel (revenue, NRR, GMV) separately, with the closest in-Mixpanel proxy, so the agent doesn't chase data that isn't here. -- **Qualified/active user definition** in this data. -- **Authority**: who owns the schema and canonical reports, whose conventions the agent should follow, when to defer to a human vs. create new entities. Highest-value field. -- **Vocabulary**: ask first whether a glossary/data dictionary exists and import it; only interview term-by-term if there's no source. - -Record in `interview_answers`. Unknowns → Open Questions, never guessed. +Cover `references/interview-questions.md`'s "Always ask if not already covered" list in full — do not skip any item on it. Record in `interview_answers` (unknowns → Open Questions per SKILL.md's "Ground everything" rule). ## Step 3 — Compose draft -Fill `references/context-template.md`: durable `tldr;` first (what/where/when/who/how/why, 1–3 sentences each, linking deeper); qualitative sections from answers; all schema facts in the fenced, timestamped Schema Snapshot; unsupported items in Open Questions. Respect the 50k cap (trim Schema Snapshot first). - -## Step 4 — Preview, diff, confirm - -Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged) — required because writes are full-replace. Prompt: - -``` -Write this to [org / project: NAME] business context? - CONFIRM — commit this exact document (replaces current context at this level) - EXPORT — save draft to a local .md file, don't write to Mixpanel - edit — tell me what to change - exit — discard -``` - -Only literal `CONFIRM` commits. For `both`, confirm each level separately. +Compose `draft_context` per SKILL.md's Write flow composition rules, with the qualitative sections drawn from `interview_answers` and the research pre-fill. -## Step 5 — Back up, then write +## Step 4 — Preview and write -Back up existing context per SKILL.md's "Back up before every write" rule, then write the full document for the level. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. +Run SKILL.md's Write flow section on the composed `draft_context`. ## Follow-on diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/status.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/status.md index f548706..dd46eb5 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/status.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/status.md @@ -17,7 +17,7 @@ For the org and (if a project is in scope) the project: ## Step 2 — Data layer (Lexicon) -If a project is in scope and `manage-lexicon` is available, run its `score-lexicon` (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. +If a project is in scope and `manage-lexicon` is available, ask it to score current coverage (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. ## Step 3 — Present one readout diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/target.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/target.md index ec6ba68..5a328b5 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/target.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/target.md @@ -20,10 +20,10 @@ Where should business context live? ## Validate permissions -Check `caller_role` for the chosen target(s). If the user lacks write permission for a level, surface it and offer alternatives: +Check `caller_role` for the chosen target(s) against SKILL.md's "Permissions gate writes" constraint (the canonical role matrix). If the user lacks write permission for a level, name the required role from that matrix and offer alternatives: -- If they can't write to org: "You need org owner/admin to write org-level context. Want to target project only?" -- If they can't write to project: "You need project owner/admin to write project context. Want to target org only, or export locally?" +- Can't write to org → offer targeting project only. +- Can't write to project → offer targeting org only, or exporting locally. ## Set and confirm diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/context-template.md index af5cfc0..a7b32a9 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/context-template.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/context-template.md @@ -1,10 +1,16 @@ # Context Template -Fixed section structure for generated context. Adapted from the who/what/where/why/how framework Mixpanel uses for native context generation, so skill output stays consistent with the in-product "Generate with AI" button. **Structure is fixed; only content varies.** Used by `import-context`, `setup-context`, and scored by `status`. +Fixed section structure for generated context. The project-level template follows the what/where/who/how/why framework used by Mixpanel's native context generation (the in-product "Generate with AI" feature) at the time of writing — verify alignment against current Mixpanel docs. The org-level template uses the subset of that framework that applies at org scope (what / who / how-we-measure-success), plus default-project routing. Whatever the native feature does today, the Org-Level and Project-Level Templates below are canonical for this skill — see `SKILL.md`'s "Structure is fixed; source, content, and target are flexible" constraint. Used by `import-context`, `setup-context`, and scored by `status`. + +## Contents +- Org-Level Template +- Project-Level Template +- Worked Example (Excerpt) +- Rules --- -## ORG-LEVEL TEMPLATE +## Org-Level Template ```markdown # [Company] — Organization Context @@ -21,11 +27,15 @@ Fixed section structure for generated context. Adapted from the who/what/where/w - **North star (in Mixpanel)**: [the Mixpanel-trackable metric that best reflects success + why] - **Supporting metrics (in Mixpanel)**: [list] - **True north star outside Mixpanel**: [e.g. revenue/NRR/GMV in another tool, + closest Mixpanel proxy — or "none, north star is trackable here"] -- **Definition of a qualified/active user**: [the exact rule the agent should apply] +- **Definition of Active/Qualified User**: [the exact rule the agent should apply] ## Customer Segments [Named segments and what distinguishes them.] +## Default Project & Routing +[Which project the agent should default to, and which project answers which kind +of question. Name any projects the agent should avoid (test, staging, sandbox).] + ## Internal Vocabulary & Acronyms [Term — meaning. Anything the agent would otherwise misread.] @@ -35,9 +45,9 @@ Fixed section structure for generated context. Adapted from the who/what/where/w --- -## PROJECT-LEVEL TEMPLATE +## Project-Level Template -```markdown +````markdown # [Project] — Project Context ## tldr; @@ -76,14 +86,42 @@ Timezone: [tz] ## Open Questions [Anything not grounded in answers, import, or schema, phrased as questions.] +```` + +--- + +## Worked Example (Excerpt) + +The bracketed placeholders in the Org-Level and Project-Level Templates are fill instructions, not output. A completed section is grounded and terse, with no placeholders — for calibration: + +````markdown +## Business +Acme runs a B2B expense-management SaaS; revenue is per-seat subscription plus +interchange on the Acme corporate card. Finance and ops teams are the buyers. + +## North Star & Key Metrics +- **North star (in Mixpanel)**: weekly active approvers — an approver who actions ≥1 expense in a rolling 7-day window; best in-product signal that the workflow is adopted. +- **True north star outside Mixpanel**: net revenue retention (lives in the billing system); closest Mixpanel proxy is seat activation rate. +```` + +And a filled project-level Schema Snapshot — the volatile-quarantine convention rendered correctly (fenced, timestamped, counts nowhere else): + +````markdown +## Schema Snapshot + +``` +Top events: Expense Submitted, Expense Approved, Report Exported +Key properties: team_id, expense_category, approver_role +Integrations in use: Segment (server-side), Snowflake import +Timezone: America/New_York ``` +```` --- ## Rules -- `tldr;` H3s are 1–3 sentences each. Terse. Point to deeper sections, don't duplicate. -- Schema-derived facts live **only** in Schema Snapshot, fenced and timestamped. -- No quantity-in-prose ("project has 26 users") — goes stale, is bloat. -- Hedging language not allowed in the body. Uncertainty → Open Questions. -- Imported content is mapped here section-by-section; it never enters raw. +- `tldr;` bullets are a single short line each — one sentence, two short clauses at most. Terse. Point to deeper sections, don't duplicate. +- Schema-derived facts follow `SKILL.md`'s "Quarantine volatile facts" rule — see the fenced, timestamped Schema Snapshot section. +- No quantity-in-prose — meaning no raw data counts or volumes ("project has 26 users", "1.2M events/day"). Metric-definition thresholds (a WAU window, "actions ≥1 expense") are part of a definition, not a data count, and are fine. At project level, data counts live only in the fenced Schema Snapshot; org-level context carries none. This is the canonical home for the rule `import-mapping.md`'s "What to drop" raw-numbers item points back to. +- Grounding and uncertainty handling follow `SKILL.md`'s "Ground everything" rule; imported content is mapped section-by-section per its "Imported content is mapped, never passed through raw" constraint. diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/import-mapping.md index 8db094d..723e9ce 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/import-mapping.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/import-mapping.md @@ -1,20 +1,33 @@ # Import Mapping -How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template. Never paste raw source into Mixpanel. +How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template — per SKILL.md's "Imported content is mapped, never passed through raw" constraint. ## Mapping table (source → template section) -| If the source has… | Map to | -|---|---| -| "About us", company overview, what we do/sell | Business / Domain & Vocabulary | -| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | -| Definition of active/qualified/engaged user, MAU/WAU logic | Definition of Qualified User | -| Customer types, segments, personas, tiers | Customer Segments | -| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | -| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | -| Data owner, schema owner, "ask X before adding events", RACI | Authority & Governance | -| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | -| Default project guidance, which project for what | Conventions & Defaults (org) | +Section names are the literal `references/context-template.md` headings — use them verbatim, never a paraphrase. One annotation is allowed in Map-to cells: an "— bullet …" suffix names a bullet *inside* the section and is not part of the heading. ("(this project)" carries no such caveat — it *is* part of the literal project-level heading.) + +| If the source has… | Map to | Level | +|---|---|---| +| "About us", company overview, what we do/sell | Business | org | +| Product/surface description, what events represent, who the tracked end-user is | Domain & Vocabulary | project | +| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | org | +| Definition of active/qualified/engaged user, MAU/WAU logic (org-wide) | North Star & Key Metrics — bullet "Definition of Active/Qualified User" | org | +| Definition of active/qualified/engaged user, MAU/WAU logic (project-specific override) | Definition of Active/Qualified User (this project) | project | +| Customer types, segments, personas, tiers | Customer Segments | org | +| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | org | +| Default-project guidance, "which project for what", projects to avoid | Default Project & Routing | org | +| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | project | +| Data owner, schema owner, "ask X before adding events" | Authority & Governance | project | +| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | project | + +Three template fields have no body section to map to. Two are filled by `import-context`'s "Fill gaps (mini-interview)" step (targeted questions for what the import left empty) instead of by import mapping: + +- The project `tldr;`'s "Why" line. +- The org `tldr;`'s "Who" line's internal-users clause (Customer Segments only covers external customer types). + +The third — the project `tldr;`'s "Where" line — is never mapped from a source doc: its integrations come from `schema_facts` (pulled live, see SKILL.md's session vocabulary), and the SDK/server/warehouse detail is confirmed via the Domain & Vocabulary "Where" question ("where does this project's data come from?") in `references/interview-questions.md`. + +`Open Questions` is never a direct mapping target either — it's populated via SKILL.md's "Ground everything" rule: anything the source can't ground lands there, not in a mapped section. Schema contradictions are one such case (see "What to drop"). ## What to drop (do not map) @@ -22,11 +35,10 @@ How to turn an arbitrary source document into template-conformant context. The s - Roadmap, upcoming features, "Q3 plans" — time-bound, not durable context. - Changelogs, migration notes, ticket references. - Anything that contradicts the live schema — flag it as an Open Question rather than importing it. -- Raw numbers/counts — schema facts come from the live pull, fenced and timestamped, not from the doc. +- Raw numbers/counts — barred by context-template.md's "no quantity-in-prose" rule; any live counts come from the schema pull, never from the doc. ## Rules -- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. +- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. E.g. from "activation is our north star, tracked on the growth pod's dashboard," map "activation" to North Star & Key Metrics and route the dashboard to Key Dashboards & Reports — don't paste the whole sentence into one section. - **Preserve the customer's own vocabulary.** If they call it "design partners" not "enterprise customers", keep their term — the agent should speak their language. - **Attribute nothing you can't ground.** If the doc implies an owner but doesn't name one, that's an Open Question, not an Authority entry. -- **Show your work.** The coverage view (import-context Step 3) must make clear which sections came from the source and which are still empty, so the user trusts the result and knows what the gap-interview will cover. diff --git a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/interview-questions.md index c30872d..5e99220 100644 --- a/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/interview-questions.md +++ b/plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/references/interview-questions.md @@ -1,51 +1,56 @@ # Interview Questions -Starter question bank, grouped by template section. **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` where noted, ask in small batches. Unknown answers → Open Questions, never guessed. +Starter question bank, grouped by template section (`tldr;` and section names are defined in `references/context-template.md`). **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` (the live schema pull — see SKILL.md's session vocabulary) where noted, ask in small batches. Unknown answers go to Open Questions per SKILL.md's "Ground everything" rule. --- ## Before interviewing — research and pre-fill -Do these first, so the interview is mostly confirmation, not blank-filling: - -1. **Web search the company.** What it does, business model, customers/segments. Draft the **Business** and **Customer Segments** sections from public sources, then present for correction (see below). Don't ask these cold. -2. **Pull the schema** into `schema_facts` (top events, key properties) — needed to anchor the north-star and event questions to what actually exists in Mixpanel. -3. **Check for a definitions source.** Before asking vocab questions, ask if one exists and import it instead. +`commands/setup-context.md`'s "Research and pull schema first" step owns the pre-fill procedure — web-search the company to draft the Business and Customer Segments sections, and pull `schema_facts`. When that step has run (the `setup-context` path, with web search available), the interview is mostly confirmation, not blank-filling. When it hasn't — no web search tool, or the `import-context` gap-filling path — use each section's fallback question and ask directly. (Checking for a definitions source before vocabulary questions is handled by the Internal Vocabulary & Acronyms subsection, which is marked "ask for a source first.") --- -## ORG LEVEL +## Org level -### Business *(pre-filled from web search — confirm, don't ask)* +### Business *(confirm the web-research draft when one exists; else use the fallback)* - Here's what I found about the company: [drafted summary]. Is this right? Anything to fix or add? - Anything about the business model or how you make money that the public description gets wrong? - -### Customer Segments *(pre-filled from web search — confirm, don't ask)* -- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? +- *(Fallback, no pre-fill)* In a sentence or two: what does the company do, and how does it make money? ### North Star & Key Metrics *(must be Mixpanel-trackable)* -- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[Verified] Query Run`, activations, something else?") +- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[X]`, activations, something else?") - What are the 2–3 supporting metrics **in Mixpanel** underneath it? -- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR, GMV in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. +- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR (net revenue retention), GMV (gross merchandise value) in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. - How do you define an "active" or "qualified" user in this data? (the exact rule) -### Vocabulary & Acronyms *(ask for a source first)* +### Customer Segments *(confirm the web-research draft when one exists; else use the fallback)* +- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? +- Which internal teams or roles use Mixpanel here (e.g. growth, product, support)? (feeds the org `tldr;`'s "Who" line — its internal-users clause) +- *(Fallback, no pre-fill)* What are your main customer types or segments, and what distinguishes them? + +### Default Project & Routing +- When someone asks a product question without naming a project, which project should the agent look in first? +- Which project answers which kind of question (e.g. web vs mobile, prod vs internal)? Any projects the agent should avoid (test, staging, sandbox)? + +### Internal Vocabulary & Acronyms *(ask for a source first)* - Do you have a glossary, data dictionary, or definitions page anywhere? If so, point me to it and I'll pull from it. - If not: what internal terms or acronyms would the agent misread? Term + meaning. (focus on words that mean something specific in *your* data — "activation", "engaged", "churned") --- -## PROJECT LEVEL +## Project level ### Domain & Vocabulary - What product or surface does this project track? (web app, mobile, backend, a specific feature) - Who is the end-user whose behavior shows up here? (your customer, an internal team, a machine/service) +- *(Seed with schema_facts' integrations)* Where does this project's data come from — client SDK, server-side, a warehouse import, or a mix? (confirms the schema-sourced "Where" line in the project `tldr;`) - *(Seed with schema_facts)* Your highest-volume events are `[X]` and `[Y]` — one line each, what do those represent? ### Event Taxonomy & Naming Conventions - How are events named here? Casing or prefix rules? (e.g. "Verb Noun", `[Verified]` prefix, snake_case) - *(Seed with schema_facts)* I see properties like `[A]` and `[B]` — what do they mean, and which matter most for analysis? - Any events or properties that look important but should be ignored? (test, deprecated, internal-only) +- How is analysis actually done here — custom entities or cohorts built on raw events, saved reports, conventions analysts follow? (feeds the project `tldr;`'s "How" line) ### Authority & Governance - Who owns the schema and the canonical reports in this project? @@ -56,10 +61,10 @@ Do these first, so the interview is mostly confirmation, not blank-filling: - Which dashboards/reports are the canonical, trusted ones? What is each for? - Where would you point a new team member first? -### Qualified User (this project) +### Definition of Active/Qualified User (this project) - Does "active" or "qualified" user mean something different here than at the org level? If so, what? -### Why / Business Impact +### Why (feeds the project `tldr;` — no dedicated body section) - What decisions does this project's analysis actually drive, and who acts on them? --- @@ -68,6 +73,11 @@ Do these first, so the interview is mostly confirmation, not blank-filling: Highest-value fields; source docs and web search usually lack them. Don't close an interview without them: -1. **Qualified/active user definition** — applied on almost every agent question. -2. **Authority** — who owns the schema and whose conventions to follow. Prevents the agent copying a random user's messy style. +1. **Active/qualified user definition** — applied on almost every agent question. +2. **Authority** — see the Authority & Governance questions; who owns the schema and whose conventions to follow, so the agent doesn't copy a random user's messy style. 3. **North star, scoped to Mixpanel** — anchored to events that exist here, with any out-of-Mixpanel true north star noted separately. +4. **Vocabulary** — see the Internal Vocabulary & Acronyms questions; check for a source before interviewing term-by-term. +5. **Why (project `tldr;`)** — see the Why question (Project level → Why). It's a tldr-only field with no body section, so `import-mapping.md` can't map it from a source doc — it must come from this list. +6. **Internal users (org `tldr;`)** — see the Customer Segments questions (Org level → Customer Segments; the internal-teams-and-roles bullet). Not covered by any external-facing source material, so `import-mapping.md` can't map it from a source doc either — it must come from this list. + +This is the canonical mandatory list — `commands/setup-context.md` and `commands/import-context.md` point here rather than restating it. diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/SKILL.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/SKILL.md index f732540..9749887 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/SKILL.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/SKILL.md @@ -1,43 +1,23 @@ --- -name: mixpanel-ai-readiness +name: prepare-ai-readiness license: Apache-2.0 description: > - Set up everything Mixpanel's AI assistants need to work well on a customer's - data: business context (org and project level) AND Lexicon metadata (event - descriptions, property descriptions, tags) that lets the agent understand the - data itself. Use whenever a user wants to get a project or org "ready for the - AI / agent / MCP", set up business context for the first time, import context - written down elsewhere, fill gaps, or check how AI-ready a project is across - the business and data layers. Also use on phrasings like — "set us up for - Mixpanel AI", "the agent keeps asking what our events mean", "make our project - agent-ready", "we have this in Notion, can you pull it in", "how ready are we - for the agent". Owns the business-context layer directly; delegates - event/property/tag enrichment to the manage-lexicon skill. Do NOT use for: - building dashboards; metric investigations; deleting data. Requires Mixpanel - MCP. Works best with manage-lexicon available. + Gets a Mixpanel org or project ready for its AI assistants — business context + and Lexicon metadata. Use to set up or import context, fill gaps, or check + AI-readiness: "set us up for Mixpanel AI", "how ready are we for the agent". + Not for dashboards or metrics. Requires Mixpanel MCP. --- # Mixpanel AI Readiness This skill gets a customer's Mixpanel setup ready for AI assistants (the in-product agent and MCP clients). "Ready" means two layers are in place: -1. **Business context** — markdown the agent reads first, at org level (who the company is) and project level (how a project is set up). The agent uses it to know the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** -2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has to guess what each event and property means on every query. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. +1. **Business context** — markdown designed to be the agent's first read, at org level (who the company is) and project level (how a project is set up), so it can ground the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** +2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has less signal for what each event and property means. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. -The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. - ---- - -# Critical constraints (read before any write) - -Properties of the underlying APIs, not preferences. +How the agent consumes each layer evolves with the product — verify current agent behavior against Mixpanel docs. -1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. The skill MUST read existing context, merge in memory, show a full diff, and require `CONFIRM` before every write. Never write a partial document. -2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. -3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. -4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. -5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. -6. **Delegate Lexicon work; don't duplicate it.** Event/property/tag enrichment runs through `manage-lexicon`. If that skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. +The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. --- @@ -94,15 +74,44 @@ If a message matches more than one, show the Command menu. The natural full-onbo 1. **No phase narration.** Output questions, previews, diffs, confirmation prompts, errors, results. Not "I'll now read your doc…". 2. **Import before interview.** Always offer to pull existing context first. Interview is the gap-filler, not the default. 3. **Read before write, always.** Populate `existing_context` for the target before composing. The diff is computed against it. -4. **Preview + diff before every context write.** Show the full proposed document and what changes vs current. Require literal `CONFIRM`. `EXPORT` saves a local `.md` without writing. Anything else cancels. -5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT`. +4. **Preview + diff before every context write.** Never write without showing the full proposed document, a diff against `existing_context`, and getting explicit confirmation. +5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT` (saves the draft to a local file instead of writing to Mixpanel — see Write flow below). 6. **Never overwrite populated content silently.** Existing sections are preserved and shown; the user chooses per section. -7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. +7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. If no local file-write capability is available (or it's denied), don't write or fail silently: print the full existing document inline so the user can save it themselves, and get explicit confirmation to proceed without a file backup. 8. **Ground everything.** Only what import or interview or `schema_facts` support. Uncertainty → Open Questions, never hedged prose. 9. **Quarantine volatile facts.** Schema counts/lists go only in the fenced, timestamped Schema Snapshot section. 10. **Delegate Lexicon, surface its result.** `enrich-data` hands off to `manage-lexicon` and captures `lexicon_score` so `status` can report both layers. 11. **Audit trail.** After every successful write, append `ai-readiness-runs/[ISO-timestamp]-[command].json` with org/target/project, command, sections or entities written, counts. 12. **`exit` always valid.** +13. **Resolve identifiers by name or ID.** Accept org/project by human-readable name or system ID. Match by ID first, then by case-insensitive name; if a name matches more than one, list the matches and ask which. + +## Write flow + +The shared tail of `setup-context` and `import-context`, and the canonical definition of the composition rules, confirmation prompt, and write sequence. Each command sources `draft_context` its own way (from interview answers, or from mapped source), but composes it by the same rules: fill `references/context-template.md` with the durable `tldr;` first; schema facts from `schema_facts` only in the fenced, timestamped Schema Snapshot; anything unsupported in Open Questions (per the "Ground everything" rule); respect the 50,000-char cap per context level (see Critical constraints below), trimming the Schema Snapshot first. From the composed draft, both do exactly this: + +1. **Preview, diff, confirm.** Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged). For `both`, show both levels together. Prompt: + ``` + Write this to [org / project: NAME / both] business context? + CONFIRM — commit this exact document (replaces current context at that level) + EXPORT — save draft to a local .md file, don't write to Mixpanel + edit — tell me what to change + exit — discard + ``` + Only literal `CONFIRM` commits; for `both`, one `CONFIRM` applies both levels (writes run per level; report each). `edit` scopes to the level named. Anything else cancels. +2. **Back up, then write.** Back up per the "Back up before every write" rule, then write the document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +--- + +# Critical constraints (read before any write) + +Properties of the underlying APIs, not preferences — every constraint below can change as Mixpanel's product evolves; verify current behavior, limits, and role requirements against Mixpanel docs before relying on the specifics. + +1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. Because of this, the skill MUST read existing context, merge in memory, and run the Write flow (full diff + `CONFIRM`) before every write. Never write a partial document. +2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. +3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. +4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. +5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. +6. **`manage-lexicon` can be unavailable.** Enrichment runs through it, per the "Delegate Lexicon, surface its result" behaviour rule. If the skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. --- @@ -115,10 +124,10 @@ Identify the org. Determine `target_level` (infer from the request, else ask: or Resolve `caller_role` for each target. Surface any level the user can't edit up front; adjust target or offer `EXPORT`. ## 3. Read existing context -Read current context for each target into `existing_context`. Mandatory — diffs and merges compute against it. +Populate `existing_context` for each target — mandatory before composing, per the "Read before write, always" rule. ## 3.5. Offer import-context first (if context is empty or thin) -**BEFORE setup-context or the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): +**BEFORE the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): **Always ask first:** ``` @@ -132,12 +141,12 @@ Do you have existing business context written down somewhere? Where should I look? (or type 'interview' to skip import) ``` -Only proceed to `setup-context` or the menu if the user explicitly declines to import or types "interview" / "skip" / "scratch". This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule). +Only proceed to `setup-context` or the menu if the user explicitly declines to import — types "interview" / "skip" / "scratch" — or explicitly invoked `setup-context` by name (asking to interview from scratch is itself a decline). This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule) without asking twice when the user already said which path they want. ## 4. Command loop -Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry, return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). +Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry if the command wrote anything (per the "Audit trail" rule — read-only commands like `status` skip it), return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). ## Reference files -- `references/context-template.md` — fixed org and project section templates (who/what/where/why/how), aligned to Mixpanel's native context generation so output is consistent with the in-product "Generate with AI" button. +- `references/context-template.md` — fixed org and project section templates, following a what/where/who/how/why framework at project level (org level uses a subset, plus default-project routing); that file carries the note on alignment with Mixpanel's native context generation. - `references/interview-questions.md` — question bank per section, including the authority question. - `references/import-mapping.md` — how to map an arbitrary source doc onto the template, what to keep, what to drop. diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/enrich-data.md index 4b107fb..1a4caf0 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/enrich-data.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/enrich-data.md @@ -10,21 +10,18 @@ Set up the Lexicon metadata the agent needs to understand the data itself: event ## Step 1 — Preconditions - A project must be in scope (`project_id`). If only org-level context was being worked on, ask which project to enrich — Lexicon is per-project. -- The caller needs project owner/admin to write Lexicon. Check `caller_role`; if missing, say so and offer to have an admin run this step. -- Confirm `manage-lexicon` is available. If it is not, tell the user the data layer can't be set up automatically right now, point them to the `manage-lexicon` skill in the Mixpanel skills repository, and return — do **not** reimplement event/property/tag editing here. +- The caller needs write permission for Lexicon (see SKILL.md's "Permissions gate writes" constraint for the role matrix). Check `caller_role`; if missing, name the required role and offer to have an admin run this step. +- Confirm `manage-lexicon` is available. If it is not, follow SKILL.md's "`manage-lexicon` can be unavailable" constraint — additionally, point the user to the `manage-lexicon` skill in the Mixpanel skills repository, then return. ## Step 2 — Hand off to manage-lexicon -Invoke `manage-lexicon` for this `project_id`. Drive it through, in order: - -1. **`score-lexicon`** — get the current metadata health (description coverage on events and properties, tag coverage). Capture the score. -2. **`enrich-and-tag`** — fill empty event descriptions, empty property descriptions, and add tags. Respect that skill's own rules: fill-only-empty (never overwrite existing metadata), add tags rather than replace, and its preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. +Hand this `project_id` to `manage-lexicon` and let it do two things, in this order: first measure current metadata health (description coverage on events and properties, tag coverage) and capture that score; then fill empty event and property descriptions and add tags — using whatever entry points that skill exposes. Respect its own guardrails (verify current behavior against that skill) — expect at least fill-only-empty (never overwrite existing metadata), add tags rather than replace, and a preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. Let `manage-lexicon` own its previews and confirmations. This command does not duplicate or wrap those prompts; the user interacts with manage-lexicon's flow directly. ## Step 3 — Capture result -After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise run `score-lexicon` once more to capture the after state. +After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise ask it to score coverage once more to capture the after state. ## Follow-on diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/import-context.md index dc72da2..fe2c319 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/import-context.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/import-context.md @@ -1,6 +1,6 @@ # Command: import-context -Pull business knowledge the customer has already written down, map it onto the fixed template, show what mapped and what's still empty, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. +Pull business knowledge the customer has already written down and turn it into template-conformant context, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. **Session reads:** `org_id`, `target_level`, `project_id`, `caller_role`, `existing_context`, `schema_facts` **Session writes:** `imported_source`, `interview_answers` (for gaps), `draft_context` @@ -16,16 +16,16 @@ Ask where the existing context lives, and accept any of: Do not assume which connector. Detect what's connected; if nothing relevant is, fall back to paste/file. If the user names a connector that isn't connected, tell them and offer paste/file or `setup-context` instead. -Store the raw retrieved text and its origin in `imported_source`. Never write this raw text to Mixpanel — it is input, not output. +Store the raw retrieved text and its origin in `imported_source` — never written to Mixpanel (see SKILL.md's "Imported content is mapped, never passed through raw" constraint). ## Step 2 — Map onto the template Using `references/import-mapping.md`, map the source onto `references/context-template.md` for the target level(s): - Pull each template section's content from the source where it exists. -- **Drop** what doesn't belong: meeting notes, roadmap, changelogs, anything time-bound or operational that isn't durable context. +- **Drop** what doesn't belong — see `references/import-mapping.md`'s "What to drop" list. - Do not invent. If a section has no source material, leave it empty and mark it for the gap step. -- Schema-derived facts still come from `schema_facts` (Step via setup-context's schema pull), not from the doc — the doc's own numbers are likely stale. +- Schema-derived facts still come from `schema_facts` (pulled during setup), not from the doc — the doc's own numbers are likely stale. ## Step 3 — Show the mapping @@ -33,27 +33,23 @@ Present a coverage view so the user sees exactly what the import produced: ``` Mapped from [source]: - ✓ Business / domain ← from doc - ✓ North star ← from doc - ✓ Vocabulary & acronyms ← from doc - ⚠ Qualified-user definition — partial, needs confirmation - ✗ Authority & governance — not found in source - ✗ Key dashboards — not found in source + ✓ Business ← from doc + ✓ North Star & Key Metrics ← from doc + ✓ Internal Vocabulary & Acronyms ← from doc + ⚠ Definition of Active/Qualified User (this project) — partial, needs confirmation + ✗ Authority & Governance — not found in source + ✗ Key Dashboards & Reports — not found in source ``` -Anything ✗ or ⚠ is a gap. +Use the literal template heading text for every row, per `references/import-mapping.md`'s verbatim-heading rule. Anything ✗ or ⚠ is a gap. ## Step 4 — Fill gaps (mini-interview) -For gaps only, ask the targeted questions from `references/interview-questions.md`. Always include the **authority** question and the **qualified-user** question if the import didn't cover them — these are the highest-value fields and source docs usually lack them. Record in `interview_answers`. Unknowns → Open Questions. +For gaps only, ask the targeted questions from `references/interview-questions.md`. Always cover that file's "Always ask if not already covered" mandatory list for anything the import didn't already fill. Record in `interview_answers` (unknowns → Open Questions per SKILL.md's "Ground everything" rule). -## Step 5 — Compose, preview, diff, confirm +## Step 5 — Compose and write -Identical to `setup-context` Steps 3–4: compose `draft_context` to the template (durable content first, schema facts fenced + timestamped, uncertainty in Open Questions), respect the 50k cap, show the full document plus a diff against `existing_context`. Only literal `CONFIRM` proceeds to write. `EXPORT` saves a local `.md`. For `both`, confirm each level separately. - -## Step 6 — Back up, then write - -Back up existing context per SKILL.md's "Back up before every write" rule, then write the composed document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. +Compose `draft_context` per SKILL.md's Write flow composition rules, with the mapped source material in its sections and gap answers from `interview_answers`. Then run SKILL.md's Write flow section. ## Follow-on diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/setup-context.md index 05a318a..b739641 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/setup-context.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/setup-context.md @@ -5,66 +5,31 @@ Build business context from scratch via a guided interview, when the customer ha **Session reads:** `org_id`, `target_level`, `project_id`, `project_name`, `caller_role`, `existing_context` **Session writes:** `schema_facts`, `interview_answers`, `draft_context` -> **CRITICAL:** If the customer *does* have existing context somewhere, prefer `import-context` and use this only to fill gaps. **Always offer import first** before starting this command. See SKILL.md's "Offer import-context first" step. - --- ## Step 0 — Confirm the user wants interview-based setup -**ALWAYS ask this first** (unless they explicitly invoked "setup-context" or typed "interview"): - -``` -Do you have existing business context written down somewhere I could pull from? - • Notion, Confluence, Google Drive, wiki, tracking plan, etc. - • Or paste/upload a file - -If yes, we'll use import-context instead (faster and more complete). -If no, I'll interview you from scratch. - -Which would you prefer? -``` - -If they have a source, hand off to `import-context` immediately. Only proceed with this command if they confirm they have nothing to import. +Run SKILL.md's "Offer import-context first" step. If they have a source, hand off to `import-context` immediately. Only proceed with this command if that step clears (per its own exemptions). ## Step 1 — Research and pull schema first Before asking the user anything (per `references/interview-questions.md`): -- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. -- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped. Counts never go into prose, only the fenced Schema Snapshot. Partial failure: continue, note the gap in Open Questions. +- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. If no web search tool is available, skip this pre-fill and ask those questions directly in Step 2 instead. +- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped, per SKILL.md's "Quarantine volatile facts" rule. Partial failure: continue, note the gap in Open Questions. ## Step 2 — Interview (gaps and internal-only facts) Work `references/interview-questions.md`, in small batches, seeded with research and `schema_facts`. Present the web-researched Business/Segments drafts for correction rather than asking from scratch. -Mandatory, do not skip: -- **North star, scoped to Mixpanel**: which *Mixpanel-trackable* metric best reflects success, anchored to real events. Capture any true north star that lives outside Mixpanel (revenue, NRR, GMV) separately, with the closest in-Mixpanel proxy, so the agent doesn't chase data that isn't here. -- **Qualified/active user definition** in this data. -- **Authority**: who owns the schema and canonical reports, whose conventions the agent should follow, when to defer to a human vs. create new entities. Highest-value field. -- **Vocabulary**: ask first whether a glossary/data dictionary exists and import it; only interview term-by-term if there's no source. - -Record in `interview_answers`. Unknowns → Open Questions, never guessed. +Cover `references/interview-questions.md`'s "Always ask if not already covered" list in full — do not skip any item on it. Record in `interview_answers` (unknowns → Open Questions per SKILL.md's "Ground everything" rule). ## Step 3 — Compose draft -Fill `references/context-template.md`: durable `tldr;` first (what/where/when/who/how/why, 1–3 sentences each, linking deeper); qualitative sections from answers; all schema facts in the fenced, timestamped Schema Snapshot; unsupported items in Open Questions. Respect the 50k cap (trim Schema Snapshot first). - -## Step 4 — Preview, diff, confirm - -Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged) — required because writes are full-replace. Prompt: - -``` -Write this to [org / project: NAME] business context? - CONFIRM — commit this exact document (replaces current context at this level) - EXPORT — save draft to a local .md file, don't write to Mixpanel - edit — tell me what to change - exit — discard -``` - -Only literal `CONFIRM` commits. For `both`, confirm each level separately. +Compose `draft_context` per SKILL.md's Write flow composition rules, with the qualitative sections drawn from `interview_answers` and the research pre-fill. -## Step 5 — Back up, then write +## Step 4 — Preview and write -Back up existing context per SKILL.md's "Back up before every write" rule, then write the full document for the level. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. +Run SKILL.md's Write flow section on the composed `draft_context`. ## Follow-on diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/status.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/status.md index f548706..dd46eb5 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/status.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/status.md @@ -17,7 +17,7 @@ For the org and (if a project is in scope) the project: ## Step 2 — Data layer (Lexicon) -If a project is in scope and `manage-lexicon` is available, run its `score-lexicon` (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. +If a project is in scope and `manage-lexicon` is available, ask it to score current coverage (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. ## Step 3 — Present one readout diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/target.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/target.md index ec6ba68..5a328b5 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/target.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/commands/target.md @@ -20,10 +20,10 @@ Where should business context live? ## Validate permissions -Check `caller_role` for the chosen target(s). If the user lacks write permission for a level, surface it and offer alternatives: +Check `caller_role` for the chosen target(s) against SKILL.md's "Permissions gate writes" constraint (the canonical role matrix). If the user lacks write permission for a level, name the required role from that matrix and offer alternatives: -- If they can't write to org: "You need org owner/admin to write org-level context. Want to target project only?" -- If they can't write to project: "You need project owner/admin to write project context. Want to target org only, or export locally?" +- Can't write to org → offer targeting project only. +- Can't write to project → offer targeting org only, or exporting locally. ## Set and confirm diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/context-template.md index af5cfc0..a7b32a9 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/context-template.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/context-template.md @@ -1,10 +1,16 @@ # Context Template -Fixed section structure for generated context. Adapted from the who/what/where/why/how framework Mixpanel uses for native context generation, so skill output stays consistent with the in-product "Generate with AI" button. **Structure is fixed; only content varies.** Used by `import-context`, `setup-context`, and scored by `status`. +Fixed section structure for generated context. The project-level template follows the what/where/who/how/why framework used by Mixpanel's native context generation (the in-product "Generate with AI" feature) at the time of writing — verify alignment against current Mixpanel docs. The org-level template uses the subset of that framework that applies at org scope (what / who / how-we-measure-success), plus default-project routing. Whatever the native feature does today, the Org-Level and Project-Level Templates below are canonical for this skill — see `SKILL.md`'s "Structure is fixed; source, content, and target are flexible" constraint. Used by `import-context`, `setup-context`, and scored by `status`. + +## Contents +- Org-Level Template +- Project-Level Template +- Worked Example (Excerpt) +- Rules --- -## ORG-LEVEL TEMPLATE +## Org-Level Template ```markdown # [Company] — Organization Context @@ -21,11 +27,15 @@ Fixed section structure for generated context. Adapted from the who/what/where/w - **North star (in Mixpanel)**: [the Mixpanel-trackable metric that best reflects success + why] - **Supporting metrics (in Mixpanel)**: [list] - **True north star outside Mixpanel**: [e.g. revenue/NRR/GMV in another tool, + closest Mixpanel proxy — or "none, north star is trackable here"] -- **Definition of a qualified/active user**: [the exact rule the agent should apply] +- **Definition of Active/Qualified User**: [the exact rule the agent should apply] ## Customer Segments [Named segments and what distinguishes them.] +## Default Project & Routing +[Which project the agent should default to, and which project answers which kind +of question. Name any projects the agent should avoid (test, staging, sandbox).] + ## Internal Vocabulary & Acronyms [Term — meaning. Anything the agent would otherwise misread.] @@ -35,9 +45,9 @@ Fixed section structure for generated context. Adapted from the who/what/where/w --- -## PROJECT-LEVEL TEMPLATE +## Project-Level Template -```markdown +````markdown # [Project] — Project Context ## tldr; @@ -76,14 +86,42 @@ Timezone: [tz] ## Open Questions [Anything not grounded in answers, import, or schema, phrased as questions.] +```` + +--- + +## Worked Example (Excerpt) + +The bracketed placeholders in the Org-Level and Project-Level Templates are fill instructions, not output. A completed section is grounded and terse, with no placeholders — for calibration: + +````markdown +## Business +Acme runs a B2B expense-management SaaS; revenue is per-seat subscription plus +interchange on the Acme corporate card. Finance and ops teams are the buyers. + +## North Star & Key Metrics +- **North star (in Mixpanel)**: weekly active approvers — an approver who actions ≥1 expense in a rolling 7-day window; best in-product signal that the workflow is adopted. +- **True north star outside Mixpanel**: net revenue retention (lives in the billing system); closest Mixpanel proxy is seat activation rate. +```` + +And a filled project-level Schema Snapshot — the volatile-quarantine convention rendered correctly (fenced, timestamped, counts nowhere else): + +````markdown +## Schema Snapshot + +``` +Top events: Expense Submitted, Expense Approved, Report Exported +Key properties: team_id, expense_category, approver_role +Integrations in use: Segment (server-side), Snowflake import +Timezone: America/New_York ``` +```` --- ## Rules -- `tldr;` H3s are 1–3 sentences each. Terse. Point to deeper sections, don't duplicate. -- Schema-derived facts live **only** in Schema Snapshot, fenced and timestamped. -- No quantity-in-prose ("project has 26 users") — goes stale, is bloat. -- Hedging language not allowed in the body. Uncertainty → Open Questions. -- Imported content is mapped here section-by-section; it never enters raw. +- `tldr;` bullets are a single short line each — one sentence, two short clauses at most. Terse. Point to deeper sections, don't duplicate. +- Schema-derived facts follow `SKILL.md`'s "Quarantine volatile facts" rule — see the fenced, timestamped Schema Snapshot section. +- No quantity-in-prose — meaning no raw data counts or volumes ("project has 26 users", "1.2M events/day"). Metric-definition thresholds (a WAU window, "actions ≥1 expense") are part of a definition, not a data count, and are fine. At project level, data counts live only in the fenced Schema Snapshot; org-level context carries none. This is the canonical home for the rule `import-mapping.md`'s "What to drop" raw-numbers item points back to. +- Grounding and uncertainty handling follow `SKILL.md`'s "Ground everything" rule; imported content is mapped section-by-section per its "Imported content is mapped, never passed through raw" constraint. diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/import-mapping.md index 8db094d..723e9ce 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/import-mapping.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/import-mapping.md @@ -1,20 +1,33 @@ # Import Mapping -How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template. Never paste raw source into Mixpanel. +How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template — per SKILL.md's "Imported content is mapped, never passed through raw" constraint. ## Mapping table (source → template section) -| If the source has… | Map to | -|---|---| -| "About us", company overview, what we do/sell | Business / Domain & Vocabulary | -| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | -| Definition of active/qualified/engaged user, MAU/WAU logic | Definition of Qualified User | -| Customer types, segments, personas, tiers | Customer Segments | -| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | -| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | -| Data owner, schema owner, "ask X before adding events", RACI | Authority & Governance | -| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | -| Default project guidance, which project for what | Conventions & Defaults (org) | +Section names are the literal `references/context-template.md` headings — use them verbatim, never a paraphrase. One annotation is allowed in Map-to cells: an "— bullet …" suffix names a bullet *inside* the section and is not part of the heading. ("(this project)" carries no such caveat — it *is* part of the literal project-level heading.) + +| If the source has… | Map to | Level | +|---|---|---| +| "About us", company overview, what we do/sell | Business | org | +| Product/surface description, what events represent, who the tracked end-user is | Domain & Vocabulary | project | +| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | org | +| Definition of active/qualified/engaged user, MAU/WAU logic (org-wide) | North Star & Key Metrics — bullet "Definition of Active/Qualified User" | org | +| Definition of active/qualified/engaged user, MAU/WAU logic (project-specific override) | Definition of Active/Qualified User (this project) | project | +| Customer types, segments, personas, tiers | Customer Segments | org | +| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | org | +| Default-project guidance, "which project for what", projects to avoid | Default Project & Routing | org | +| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | project | +| Data owner, schema owner, "ask X before adding events" | Authority & Governance | project | +| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | project | + +Three template fields have no body section to map to. Two are filled by `import-context`'s "Fill gaps (mini-interview)" step (targeted questions for what the import left empty) instead of by import mapping: + +- The project `tldr;`'s "Why" line. +- The org `tldr;`'s "Who" line's internal-users clause (Customer Segments only covers external customer types). + +The third — the project `tldr;`'s "Where" line — is never mapped from a source doc: its integrations come from `schema_facts` (pulled live, see SKILL.md's session vocabulary), and the SDK/server/warehouse detail is confirmed via the Domain & Vocabulary "Where" question ("where does this project's data come from?") in `references/interview-questions.md`. + +`Open Questions` is never a direct mapping target either — it's populated via SKILL.md's "Ground everything" rule: anything the source can't ground lands there, not in a mapped section. Schema contradictions are one such case (see "What to drop"). ## What to drop (do not map) @@ -22,11 +35,10 @@ How to turn an arbitrary source document into template-conformant context. The s - Roadmap, upcoming features, "Q3 plans" — time-bound, not durable context. - Changelogs, migration notes, ticket references. - Anything that contradicts the live schema — flag it as an Open Question rather than importing it. -- Raw numbers/counts — schema facts come from the live pull, fenced and timestamped, not from the doc. +- Raw numbers/counts — barred by context-template.md's "no quantity-in-prose" rule; any live counts come from the schema pull, never from the doc. ## Rules -- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. +- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. E.g. from "activation is our north star, tracked on the growth pod's dashboard," map "activation" to North Star & Key Metrics and route the dashboard to Key Dashboards & Reports — don't paste the whole sentence into one section. - **Preserve the customer's own vocabulary.** If they call it "design partners" not "enterprise customers", keep their term — the agent should speak their language. - **Attribute nothing you can't ground.** If the doc implies an owner but doesn't name one, that's an Open Question, not an Authority entry. -- **Show your work.** The coverage view (import-context Step 3) must make clear which sections came from the source and which are still empty, so the user trusts the result and knows what the gap-interview will cover. diff --git a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/interview-questions.md index c30872d..5e99220 100644 --- a/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/interview-questions.md +++ b/plugins/mixpanel-mcp-in/skills/prepare-ai-readiness/references/interview-questions.md @@ -1,51 +1,56 @@ # Interview Questions -Starter question bank, grouped by template section. **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` where noted, ask in small batches. Unknown answers → Open Questions, never guessed. +Starter question bank, grouped by template section (`tldr;` and section names are defined in `references/context-template.md`). **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` (the live schema pull — see SKILL.md's session vocabulary) where noted, ask in small batches. Unknown answers go to Open Questions per SKILL.md's "Ground everything" rule. --- ## Before interviewing — research and pre-fill -Do these first, so the interview is mostly confirmation, not blank-filling: - -1. **Web search the company.** What it does, business model, customers/segments. Draft the **Business** and **Customer Segments** sections from public sources, then present for correction (see below). Don't ask these cold. -2. **Pull the schema** into `schema_facts` (top events, key properties) — needed to anchor the north-star and event questions to what actually exists in Mixpanel. -3. **Check for a definitions source.** Before asking vocab questions, ask if one exists and import it instead. +`commands/setup-context.md`'s "Research and pull schema first" step owns the pre-fill procedure — web-search the company to draft the Business and Customer Segments sections, and pull `schema_facts`. When that step has run (the `setup-context` path, with web search available), the interview is mostly confirmation, not blank-filling. When it hasn't — no web search tool, or the `import-context` gap-filling path — use each section's fallback question and ask directly. (Checking for a definitions source before vocabulary questions is handled by the Internal Vocabulary & Acronyms subsection, which is marked "ask for a source first.") --- -## ORG LEVEL +## Org level -### Business *(pre-filled from web search — confirm, don't ask)* +### Business *(confirm the web-research draft when one exists; else use the fallback)* - Here's what I found about the company: [drafted summary]. Is this right? Anything to fix or add? - Anything about the business model or how you make money that the public description gets wrong? - -### Customer Segments *(pre-filled from web search — confirm, don't ask)* -- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? +- *(Fallback, no pre-fill)* In a sentence or two: what does the company do, and how does it make money? ### North Star & Key Metrics *(must be Mixpanel-trackable)* -- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[Verified] Query Run`, activations, something else?") +- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[X]`, activations, something else?") - What are the 2–3 supporting metrics **in Mixpanel** underneath it? -- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR, GMV in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. +- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR (net revenue retention), GMV (gross merchandise value) in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. - How do you define an "active" or "qualified" user in this data? (the exact rule) -### Vocabulary & Acronyms *(ask for a source first)* +### Customer Segments *(confirm the web-research draft when one exists; else use the fallback)* +- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? +- Which internal teams or roles use Mixpanel here (e.g. growth, product, support)? (feeds the org `tldr;`'s "Who" line — its internal-users clause) +- *(Fallback, no pre-fill)* What are your main customer types or segments, and what distinguishes them? + +### Default Project & Routing +- When someone asks a product question without naming a project, which project should the agent look in first? +- Which project answers which kind of question (e.g. web vs mobile, prod vs internal)? Any projects the agent should avoid (test, staging, sandbox)? + +### Internal Vocabulary & Acronyms *(ask for a source first)* - Do you have a glossary, data dictionary, or definitions page anywhere? If so, point me to it and I'll pull from it. - If not: what internal terms or acronyms would the agent misread? Term + meaning. (focus on words that mean something specific in *your* data — "activation", "engaged", "churned") --- -## PROJECT LEVEL +## Project level ### Domain & Vocabulary - What product or surface does this project track? (web app, mobile, backend, a specific feature) - Who is the end-user whose behavior shows up here? (your customer, an internal team, a machine/service) +- *(Seed with schema_facts' integrations)* Where does this project's data come from — client SDK, server-side, a warehouse import, or a mix? (confirms the schema-sourced "Where" line in the project `tldr;`) - *(Seed with schema_facts)* Your highest-volume events are `[X]` and `[Y]` — one line each, what do those represent? ### Event Taxonomy & Naming Conventions - How are events named here? Casing or prefix rules? (e.g. "Verb Noun", `[Verified]` prefix, snake_case) - *(Seed with schema_facts)* I see properties like `[A]` and `[B]` — what do they mean, and which matter most for analysis? - Any events or properties that look important but should be ignored? (test, deprecated, internal-only) +- How is analysis actually done here — custom entities or cohorts built on raw events, saved reports, conventions analysts follow? (feeds the project `tldr;`'s "How" line) ### Authority & Governance - Who owns the schema and the canonical reports in this project? @@ -56,10 +61,10 @@ Do these first, so the interview is mostly confirmation, not blank-filling: - Which dashboards/reports are the canonical, trusted ones? What is each for? - Where would you point a new team member first? -### Qualified User (this project) +### Definition of Active/Qualified User (this project) - Does "active" or "qualified" user mean something different here than at the org level? If so, what? -### Why / Business Impact +### Why (feeds the project `tldr;` — no dedicated body section) - What decisions does this project's analysis actually drive, and who acts on them? --- @@ -68,6 +73,11 @@ Do these first, so the interview is mostly confirmation, not blank-filling: Highest-value fields; source docs and web search usually lack them. Don't close an interview without them: -1. **Qualified/active user definition** — applied on almost every agent question. -2. **Authority** — who owns the schema and whose conventions to follow. Prevents the agent copying a random user's messy style. +1. **Active/qualified user definition** — applied on almost every agent question. +2. **Authority** — see the Authority & Governance questions; who owns the schema and whose conventions to follow, so the agent doesn't copy a random user's messy style. 3. **North star, scoped to Mixpanel** — anchored to events that exist here, with any out-of-Mixpanel true north star noted separately. +4. **Vocabulary** — see the Internal Vocabulary & Acronyms questions; check for a source before interviewing term-by-term. +5. **Why (project `tldr;`)** — see the Why question (Project level → Why). It's a tldr-only field with no body section, so `import-mapping.md` can't map it from a source doc — it must come from this list. +6. **Internal users (org `tldr;`)** — see the Customer Segments questions (Org level → Customer Segments; the internal-teams-and-roles bullet). Not covered by any external-facing source material, so `import-mapping.md` can't map it from a source doc either — it must come from this list. + +This is the canonical mandatory list — `commands/setup-context.md` and `commands/import-context.md` point here rather than restating it. diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/SKILL.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/SKILL.md index f732540..9749887 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/SKILL.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/SKILL.md @@ -1,43 +1,23 @@ --- -name: mixpanel-ai-readiness +name: prepare-ai-readiness license: Apache-2.0 description: > - Set up everything Mixpanel's AI assistants need to work well on a customer's - data: business context (org and project level) AND Lexicon metadata (event - descriptions, property descriptions, tags) that lets the agent understand the - data itself. Use whenever a user wants to get a project or org "ready for the - AI / agent / MCP", set up business context for the first time, import context - written down elsewhere, fill gaps, or check how AI-ready a project is across - the business and data layers. Also use on phrasings like — "set us up for - Mixpanel AI", "the agent keeps asking what our events mean", "make our project - agent-ready", "we have this in Notion, can you pull it in", "how ready are we - for the agent". Owns the business-context layer directly; delegates - event/property/tag enrichment to the manage-lexicon skill. Do NOT use for: - building dashboards; metric investigations; deleting data. Requires Mixpanel - MCP. Works best with manage-lexicon available. + Gets a Mixpanel org or project ready for its AI assistants — business context + and Lexicon metadata. Use to set up or import context, fill gaps, or check + AI-readiness: "set us up for Mixpanel AI", "how ready are we for the agent". + Not for dashboards or metrics. Requires Mixpanel MCP. --- # Mixpanel AI Readiness This skill gets a customer's Mixpanel setup ready for AI assistants (the in-product agent and MCP clients). "Ready" means two layers are in place: -1. **Business context** — markdown the agent reads first, at org level (who the company is) and project level (how a project is set up). The agent uses it to know the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** -2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has to guess what each event and property means on every query. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. +1. **Business context** — markdown designed to be the agent's first read, at org level (who the company is) and project level (how a project is set up), so it can ground the north star, what a "qualified user" means, which project to default to, and the team's conventions. **This skill owns this layer.** +2. **Lexicon metadata** — descriptions on events, descriptions on properties, and tags. Without these the agent has less signal for what each event and property means. **This skill delegates this layer to the `manage-lexicon` skill**, run inline, rather than reimplementing it. -The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. - ---- - -# Critical constraints (read before any write) - -Properties of the underlying APIs, not preferences. +How the agent consumes each layer evolves with the product — verify current agent behavior against Mixpanel docs. -1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. The skill MUST read existing context, merge in memory, show a full diff, and require `CONFIRM` before every write. Never write a partial document. -2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. -3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. -4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. -5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. -6. **Delegate Lexicon work; don't duplicate it.** Event/property/tag enrichment runs through `manage-lexicon`. If that skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. +The skill is import-first: if the customer already has their business knowledge written down somewhere (Notion, a Google Doc, a tracking-plan sheet, a PRD, a pasted block), it pulls that in and maps it onto the template, then interviews only to fill what's missing. It runs as a single interactive session and writes only after explicit preview and confirmation. --- @@ -94,15 +74,44 @@ If a message matches more than one, show the Command menu. The natural full-onbo 1. **No phase narration.** Output questions, previews, diffs, confirmation prompts, errors, results. Not "I'll now read your doc…". 2. **Import before interview.** Always offer to pull existing context first. Interview is the gap-filler, not the default. 3. **Read before write, always.** Populate `existing_context` for the target before composing. The diff is computed against it. -4. **Preview + diff before every context write.** Show the full proposed document and what changes vs current. Require literal `CONFIRM`. `EXPORT` saves a local `.md` without writing. Anything else cancels. -5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT`. +4. **Preview + diff before every context write.** Never write without showing the full proposed document, a diff against `existing_context`, and getting explicit confirmation. +5. **Permission pre-check** for each target before doing unsaveable work; offer a level the user can edit, or `EXPORT` (saves the draft to a local file instead of writing to Mixpanel — see Write flow below). 6. **Never overwrite populated content silently.** Existing sections are preserved and shown; the user chooses per section. -7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. +7. **Back up before every write.** Before writing, save the existing context to `backups/{level}-{id}-backup-{ISO-timestamp}.md` (an empty file with a note if context was empty) and report the path — so a prior version can be restored manually if a write turns out to be wrong. If no local file-write capability is available (or it's denied), don't write or fail silently: print the full existing document inline so the user can save it themselves, and get explicit confirmation to proceed without a file backup. 8. **Ground everything.** Only what import or interview or `schema_facts` support. Uncertainty → Open Questions, never hedged prose. 9. **Quarantine volatile facts.** Schema counts/lists go only in the fenced, timestamped Schema Snapshot section. 10. **Delegate Lexicon, surface its result.** `enrich-data` hands off to `manage-lexicon` and captures `lexicon_score` so `status` can report both layers. 11. **Audit trail.** After every successful write, append `ai-readiness-runs/[ISO-timestamp]-[command].json` with org/target/project, command, sections or entities written, counts. 12. **`exit` always valid.** +13. **Resolve identifiers by name or ID.** Accept org/project by human-readable name or system ID. Match by ID first, then by case-insensitive name; if a name matches more than one, list the matches and ask which. + +## Write flow + +The shared tail of `setup-context` and `import-context`, and the canonical definition of the composition rules, confirmation prompt, and write sequence. Each command sources `draft_context` its own way (from interview answers, or from mapped source), but composes it by the same rules: fill `references/context-template.md` with the durable `tldr;` first; schema facts from `schema_facts` only in the fenced, timestamped Schema Snapshot; anything unsupported in Open Questions (per the "Ground everything" rule); respect the 50,000-char cap per context level (see Critical constraints below), trimming the Schema Snapshot first. From the composed draft, both do exactly this: + +1. **Preview, diff, confirm.** Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged). For `both`, show both levels together. Prompt: + ``` + Write this to [org / project: NAME / both] business context? + CONFIRM — commit this exact document (replaces current context at that level) + EXPORT — save draft to a local .md file, don't write to Mixpanel + edit — tell me what to change + exit — discard + ``` + Only literal `CONFIRM` commits; for `both`, one `CONFIRM` applies both levels (writes run per level; report each). `edit` scopes to the level named. Anything else cancels. +2. **Back up, then write.** Back up per the "Back up before every write" rule, then write the document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. + +--- + +# Critical constraints (read before any write) + +Properties of the underlying APIs, not preferences — every constraint below can change as Mixpanel's product evolves; verify current behavior, limits, and role requirements against Mixpanel docs before relying on the specifics. + +1. **Writing business context is full-replace.** No append/merge — the business-context write tool replaces the *entire* context at the target level. Because of this, the skill MUST read existing context, merge in memory, and run the Write flow (full diff + `CONFIRM`) before every write. Never write a partial document. +2. **Permissions gate writes.** Org context needs org owner/admin; project context needs project owner/admin. Lexicon writes need project owner/admin. Anyone with project access can *read*. Check the caller's role for each target **before** doing work the user can't save. +3. **Markdown only, 50,000-char cap per context level.** Links/images/structured data in context are not fetched by the agent. If a draft nears the cap, trim the Schema Snapshot first. +4. **Imported content is mapped, never passed through raw.** An existing doc is a *source*, not the output. Read it, map onto the fixed template, show what mapped and what's still empty, then confirm. Do not paste a customer's raw doc into business context. +5. **Structure is fixed; source, content, and target are flexible.** The user chooses where context comes *from* (any connector or a file) and where it lives (org / project / both). The user never freehands the section structure. +6. **`manage-lexicon` can be unavailable.** Enrichment runs through it, per the "Delegate Lexicon, surface its result" behaviour rule. If the skill is unavailable, say so and let the user proceed with the business-context layer only — do not silently reimplement enrichment. --- @@ -115,10 +124,10 @@ Identify the org. Determine `target_level` (infer from the request, else ask: or Resolve `caller_role` for each target. Surface any level the user can't edit up front; adjust target or offer `EXPORT`. ## 3. Read existing context -Read current context for each target into `existing_context`. Mandatory — diffs and merges compute against it. +Populate `existing_context` for each target — mandatory before composing, per the "Read before write, always" rule. ## 3.5. Offer import-context first (if context is empty or thin) -**BEFORE setup-context or the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): +**BEFORE the command menu**, if the existing context for the target level is empty or minimal (< 500 chars): **Always ask first:** ``` @@ -132,12 +141,12 @@ Do you have existing business context written down somewhere? Where should I look? (or type 'interview' to skip import) ``` -Only proceed to `setup-context` or the menu if the user explicitly declines to import or types "interview" / "skip" / "scratch". This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule). +Only proceed to `setup-context` or the menu if the user explicitly declines to import — types "interview" / "skip" / "scratch" — or explicitly invoked `setup-context` by name (asking to interview from scratch is itself a decline). This ensures most customers start with import-context (the preferred path per the "Import before interview" behaviour rule) without asking twice when the user already said which path they want. ## 4. Command loop -Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry, return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). +Choose command (explicit → implicit → menu), load `commands/[command].md`, execute reusing session state, print `✅ Done.`, write the audit entry if the command wrote anything (per the "Audit trail" rule — read-only commands like `status` skip it), return to selection. Honour follow-on offers (Status → Import/Setup/Enrich; Import → Setup for gaps → Enrich). ## Reference files -- `references/context-template.md` — fixed org and project section templates (who/what/where/why/how), aligned to Mixpanel's native context generation so output is consistent with the in-product "Generate with AI" button. +- `references/context-template.md` — fixed org and project section templates, following a what/where/who/how/why framework at project level (org level uses a subset, plus default-project routing); that file carries the note on alignment with Mixpanel's native context generation. - `references/interview-questions.md` — question bank per section, including the authority question. - `references/import-mapping.md` — how to map an arbitrary source doc onto the template, what to keep, what to drop. diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/enrich-data.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/enrich-data.md index 4b107fb..1a4caf0 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/enrich-data.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/enrich-data.md @@ -10,21 +10,18 @@ Set up the Lexicon metadata the agent needs to understand the data itself: event ## Step 1 — Preconditions - A project must be in scope (`project_id`). If only org-level context was being worked on, ask which project to enrich — Lexicon is per-project. -- The caller needs project owner/admin to write Lexicon. Check `caller_role`; if missing, say so and offer to have an admin run this step. -- Confirm `manage-lexicon` is available. If it is not, tell the user the data layer can't be set up automatically right now, point them to the `manage-lexicon` skill in the Mixpanel skills repository, and return — do **not** reimplement event/property/tag editing here. +- The caller needs write permission for Lexicon (see SKILL.md's "Permissions gate writes" constraint for the role matrix). Check `caller_role`; if missing, name the required role and offer to have an admin run this step. +- Confirm `manage-lexicon` is available. If it is not, follow SKILL.md's "`manage-lexicon` can be unavailable" constraint — additionally, point the user to the `manage-lexicon` skill in the Mixpanel skills repository, then return. ## Step 2 — Hand off to manage-lexicon -Invoke `manage-lexicon` for this `project_id`. Drive it through, in order: - -1. **`score-lexicon`** — get the current metadata health (description coverage on events and properties, tag coverage). Capture the score. -2. **`enrich-and-tag`** — fill empty event descriptions, empty property descriptions, and add tags. Respect that skill's own rules: fill-only-empty (never overwrite existing metadata), add tags rather than replace, and its preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. +Hand this `project_id` to `manage-lexicon` and let it do two things, in this order: first measure current metadata health (description coverage on events and properties, tag coverage) and capture that score; then fill empty event and property descriptions and add tags — using whatever entry points that skill exposes. Respect its own guardrails (verify current behavior against that skill) — expect at least fill-only-empty (never overwrite existing metadata), add tags rather than replace, and a preview + `CONFIRM` gate before writes. Those guardrails are the reason we delegate rather than rebuild — don't bypass them. Let `manage-lexicon` own its previews and confirmations. This command does not duplicate or wrap those prompts; the user interacts with manage-lexicon's flow directly. ## Step 3 — Capture result -After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise run `score-lexicon` once more to capture the after state. +After enrichment, record the post-run coverage into `lexicon_score` (events described %, properties described %, events tagged %), so `status` can show both layers in one readout. If `manage-lexicon` ran a final score, reuse it; otherwise ask it to score coverage once more to capture the after state. ## Follow-on diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/import-context.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/import-context.md index dc72da2..fe2c319 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/import-context.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/import-context.md @@ -1,6 +1,6 @@ # Command: import-context -Pull business knowledge the customer has already written down, map it onto the fixed template, show what mapped and what's still empty, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. +Pull business knowledge the customer has already written down and turn it into template-conformant context, then write on `CONFIRM`. This is the preferred starting path — most customers have *something* already, and adapting it beats a cold interview. **Session reads:** `org_id`, `target_level`, `project_id`, `caller_role`, `existing_context`, `schema_facts` **Session writes:** `imported_source`, `interview_answers` (for gaps), `draft_context` @@ -16,16 +16,16 @@ Ask where the existing context lives, and accept any of: Do not assume which connector. Detect what's connected; if nothing relevant is, fall back to paste/file. If the user names a connector that isn't connected, tell them and offer paste/file or `setup-context` instead. -Store the raw retrieved text and its origin in `imported_source`. Never write this raw text to Mixpanel — it is input, not output. +Store the raw retrieved text and its origin in `imported_source` — never written to Mixpanel (see SKILL.md's "Imported content is mapped, never passed through raw" constraint). ## Step 2 — Map onto the template Using `references/import-mapping.md`, map the source onto `references/context-template.md` for the target level(s): - Pull each template section's content from the source where it exists. -- **Drop** what doesn't belong: meeting notes, roadmap, changelogs, anything time-bound or operational that isn't durable context. +- **Drop** what doesn't belong — see `references/import-mapping.md`'s "What to drop" list. - Do not invent. If a section has no source material, leave it empty and mark it for the gap step. -- Schema-derived facts still come from `schema_facts` (Step via setup-context's schema pull), not from the doc — the doc's own numbers are likely stale. +- Schema-derived facts still come from `schema_facts` (pulled during setup), not from the doc — the doc's own numbers are likely stale. ## Step 3 — Show the mapping @@ -33,27 +33,23 @@ Present a coverage view so the user sees exactly what the import produced: ``` Mapped from [source]: - ✓ Business / domain ← from doc - ✓ North star ← from doc - ✓ Vocabulary & acronyms ← from doc - ⚠ Qualified-user definition — partial, needs confirmation - ✗ Authority & governance — not found in source - ✗ Key dashboards — not found in source + ✓ Business ← from doc + ✓ North Star & Key Metrics ← from doc + ✓ Internal Vocabulary & Acronyms ← from doc + ⚠ Definition of Active/Qualified User (this project) — partial, needs confirmation + ✗ Authority & Governance — not found in source + ✗ Key Dashboards & Reports — not found in source ``` -Anything ✗ or ⚠ is a gap. +Use the literal template heading text for every row, per `references/import-mapping.md`'s verbatim-heading rule. Anything ✗ or ⚠ is a gap. ## Step 4 — Fill gaps (mini-interview) -For gaps only, ask the targeted questions from `references/interview-questions.md`. Always include the **authority** question and the **qualified-user** question if the import didn't cover them — these are the highest-value fields and source docs usually lack them. Record in `interview_answers`. Unknowns → Open Questions. +For gaps only, ask the targeted questions from `references/interview-questions.md`. Always cover that file's "Always ask if not already covered" mandatory list for anything the import didn't already fill. Record in `interview_answers` (unknowns → Open Questions per SKILL.md's "Ground everything" rule). -## Step 5 — Compose, preview, diff, confirm +## Step 5 — Compose and write -Identical to `setup-context` Steps 3–4: compose `draft_context` to the template (durable content first, schema facts fenced + timestamped, uncertainty in Open Questions), respect the 50k cap, show the full document plus a diff against `existing_context`. Only literal `CONFIRM` proceeds to write. `EXPORT` saves a local `.md`. For `both`, confirm each level separately. - -## Step 6 — Back up, then write - -Back up existing context per SKILL.md's "Back up before every write" rule, then write the composed document. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. +Compose `draft_context` per SKILL.md's Write flow composition rules, with the mapped source material in its sections and gap answers from `interview_answers`. Then run SKILL.md's Write flow section. ## Follow-on diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/setup-context.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/setup-context.md index 05a318a..b739641 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/setup-context.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/setup-context.md @@ -5,66 +5,31 @@ Build business context from scratch via a guided interview, when the customer ha **Session reads:** `org_id`, `target_level`, `project_id`, `project_name`, `caller_role`, `existing_context` **Session writes:** `schema_facts`, `interview_answers`, `draft_context` -> **CRITICAL:** If the customer *does* have existing context somewhere, prefer `import-context` and use this only to fill gaps. **Always offer import first** before starting this command. See SKILL.md's "Offer import-context first" step. - --- ## Step 0 — Confirm the user wants interview-based setup -**ALWAYS ask this first** (unless they explicitly invoked "setup-context" or typed "interview"): - -``` -Do you have existing business context written down somewhere I could pull from? - • Notion, Confluence, Google Drive, wiki, tracking plan, etc. - • Or paste/upload a file - -If yes, we'll use import-context instead (faster and more complete). -If no, I'll interview you from scratch. - -Which would you prefer? -``` - -If they have a source, hand off to `import-context` immediately. Only proceed with this command if they confirm they have nothing to import. +Run SKILL.md's "Offer import-context first" step. If they have a source, hand off to `import-context` immediately. Only proceed with this command if that step clears (per its own exemptions). ## Step 1 — Research and pull schema first Before asking the user anything (per `references/interview-questions.md`): -- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. -- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped. Counts never go into prose, only the fenced Schema Snapshot. Partial failure: continue, note the gap in Open Questions. +- **Web search the company** and draft the Business and Customer Segments sections from public sources — these are confirmed, not asked cold. If no web search tool is available, skip this pre-fill and ask those questions directly in Step 2 instead. +- **Pull schema facts** into `schema_facts` (top ~10 events, ~15 properties, integrations, timezone, recency), timestamped, per SKILL.md's "Quarantine volatile facts" rule. Partial failure: continue, note the gap in Open Questions. ## Step 2 — Interview (gaps and internal-only facts) Work `references/interview-questions.md`, in small batches, seeded with research and `schema_facts`. Present the web-researched Business/Segments drafts for correction rather than asking from scratch. -Mandatory, do not skip: -- **North star, scoped to Mixpanel**: which *Mixpanel-trackable* metric best reflects success, anchored to real events. Capture any true north star that lives outside Mixpanel (revenue, NRR, GMV) separately, with the closest in-Mixpanel proxy, so the agent doesn't chase data that isn't here. -- **Qualified/active user definition** in this data. -- **Authority**: who owns the schema and canonical reports, whose conventions the agent should follow, when to defer to a human vs. create new entities. Highest-value field. -- **Vocabulary**: ask first whether a glossary/data dictionary exists and import it; only interview term-by-term if there's no source. - -Record in `interview_answers`. Unknowns → Open Questions, never guessed. +Cover `references/interview-questions.md`'s "Always ask if not already covered" list in full — do not skip any item on it. Record in `interview_answers` (unknowns → Open Questions per SKILL.md's "Ground everything" rule). ## Step 3 — Compose draft -Fill `references/context-template.md`: durable `tldr;` first (what/where/when/who/how/why, 1–3 sentences each, linking deeper); qualitative sections from answers; all schema facts in the fenced, timestamped Schema Snapshot; unsupported items in Open Questions. Respect the 50k cap (trim Schema Snapshot first). - -## Step 4 — Preview, diff, confirm - -Show the full proposed document and a diff against `existing_context` (added/changed/removed/unchanged) — required because writes are full-replace. Prompt: - -``` -Write this to [org / project: NAME] business context? - CONFIRM — commit this exact document (replaces current context at this level) - EXPORT — save draft to a local .md file, don't write to Mixpanel - edit — tell me what to change - exit — discard -``` - -Only literal `CONFIRM` commits. For `both`, confirm each level separately. +Compose `draft_context` per SKILL.md's Write flow composition rules, with the qualitative sections drawn from `interview_answers` and the research pre-fill. -## Step 5 — Back up, then write +## Step 4 — Preview and write -Back up existing context per SKILL.md's "Back up before every write" rule, then write the full document for the level. Report level + char count. On permission error, fall back to `EXPORT` and name the required role. +Run SKILL.md's Write flow section on the composed `draft_context`. ## Follow-on diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/status.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/status.md index f548706..dd46eb5 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/status.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/status.md @@ -17,7 +17,7 @@ For the org and (if a project is in scope) the project: ## Step 2 — Data layer (Lexicon) -If a project is in scope and `manage-lexicon` is available, run its `score-lexicon` (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. +If a project is in scope and `manage-lexicon` is available, ask it to score current coverage (or reuse `lexicon_score` if fresh this session) to get event-description, property-description, and tag coverage. If `manage-lexicon` is unavailable, mark the data layer "not measured" rather than guessing. ## Step 3 — Present one readout diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/target.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/target.md index ec6ba68..5a328b5 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/target.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/commands/target.md @@ -20,10 +20,10 @@ Where should business context live? ## Validate permissions -Check `caller_role` for the chosen target(s). If the user lacks write permission for a level, surface it and offer alternatives: +Check `caller_role` for the chosen target(s) against SKILL.md's "Permissions gate writes" constraint (the canonical role matrix). If the user lacks write permission for a level, name the required role from that matrix and offer alternatives: -- If they can't write to org: "You need org owner/admin to write org-level context. Want to target project only?" -- If they can't write to project: "You need project owner/admin to write project context. Want to target org only, or export locally?" +- Can't write to org → offer targeting project only. +- Can't write to project → offer targeting org only, or exporting locally. ## Set and confirm diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/context-template.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/context-template.md index af5cfc0..a7b32a9 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/context-template.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/context-template.md @@ -1,10 +1,16 @@ # Context Template -Fixed section structure for generated context. Adapted from the who/what/where/why/how framework Mixpanel uses for native context generation, so skill output stays consistent with the in-product "Generate with AI" button. **Structure is fixed; only content varies.** Used by `import-context`, `setup-context`, and scored by `status`. +Fixed section structure for generated context. The project-level template follows the what/where/who/how/why framework used by Mixpanel's native context generation (the in-product "Generate with AI" feature) at the time of writing — verify alignment against current Mixpanel docs. The org-level template uses the subset of that framework that applies at org scope (what / who / how-we-measure-success), plus default-project routing. Whatever the native feature does today, the Org-Level and Project-Level Templates below are canonical for this skill — see `SKILL.md`'s "Structure is fixed; source, content, and target are flexible" constraint. Used by `import-context`, `setup-context`, and scored by `status`. + +## Contents +- Org-Level Template +- Project-Level Template +- Worked Example (Excerpt) +- Rules --- -## ORG-LEVEL TEMPLATE +## Org-Level Template ```markdown # [Company] — Organization Context @@ -21,11 +27,15 @@ Fixed section structure for generated context. Adapted from the who/what/where/w - **North star (in Mixpanel)**: [the Mixpanel-trackable metric that best reflects success + why] - **Supporting metrics (in Mixpanel)**: [list] - **True north star outside Mixpanel**: [e.g. revenue/NRR/GMV in another tool, + closest Mixpanel proxy — or "none, north star is trackable here"] -- **Definition of a qualified/active user**: [the exact rule the agent should apply] +- **Definition of Active/Qualified User**: [the exact rule the agent should apply] ## Customer Segments [Named segments and what distinguishes them.] +## Default Project & Routing +[Which project the agent should default to, and which project answers which kind +of question. Name any projects the agent should avoid (test, staging, sandbox).] + ## Internal Vocabulary & Acronyms [Term — meaning. Anything the agent would otherwise misread.] @@ -35,9 +45,9 @@ Fixed section structure for generated context. Adapted from the who/what/where/w --- -## PROJECT-LEVEL TEMPLATE +## Project-Level Template -```markdown +````markdown # [Project] — Project Context ## tldr; @@ -76,14 +86,42 @@ Timezone: [tz] ## Open Questions [Anything not grounded in answers, import, or schema, phrased as questions.] +```` + +--- + +## Worked Example (Excerpt) + +The bracketed placeholders in the Org-Level and Project-Level Templates are fill instructions, not output. A completed section is grounded and terse, with no placeholders — for calibration: + +````markdown +## Business +Acme runs a B2B expense-management SaaS; revenue is per-seat subscription plus +interchange on the Acme corporate card. Finance and ops teams are the buyers. + +## North Star & Key Metrics +- **North star (in Mixpanel)**: weekly active approvers — an approver who actions ≥1 expense in a rolling 7-day window; best in-product signal that the workflow is adopted. +- **True north star outside Mixpanel**: net revenue retention (lives in the billing system); closest Mixpanel proxy is seat activation rate. +```` + +And a filled project-level Schema Snapshot — the volatile-quarantine convention rendered correctly (fenced, timestamped, counts nowhere else): + +````markdown +## Schema Snapshot + +``` +Top events: Expense Submitted, Expense Approved, Report Exported +Key properties: team_id, expense_category, approver_role +Integrations in use: Segment (server-side), Snowflake import +Timezone: America/New_York ``` +```` --- ## Rules -- `tldr;` H3s are 1–3 sentences each. Terse. Point to deeper sections, don't duplicate. -- Schema-derived facts live **only** in Schema Snapshot, fenced and timestamped. -- No quantity-in-prose ("project has 26 users") — goes stale, is bloat. -- Hedging language not allowed in the body. Uncertainty → Open Questions. -- Imported content is mapped here section-by-section; it never enters raw. +- `tldr;` bullets are a single short line each — one sentence, two short clauses at most. Terse. Point to deeper sections, don't duplicate. +- Schema-derived facts follow `SKILL.md`'s "Quarantine volatile facts" rule — see the fenced, timestamped Schema Snapshot section. +- No quantity-in-prose — meaning no raw data counts or volumes ("project has 26 users", "1.2M events/day"). Metric-definition thresholds (a WAU window, "actions ≥1 expense") are part of a definition, not a data count, and are fine. At project level, data counts live only in the fenced Schema Snapshot; org-level context carries none. This is the canonical home for the rule `import-mapping.md`'s "What to drop" raw-numbers item points back to. +- Grounding and uncertainty handling follow `SKILL.md`'s "Ground everything" rule; imported content is mapped section-by-section per its "Imported content is mapped, never passed through raw" constraint. diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/import-mapping.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/import-mapping.md index 8db094d..723e9ce 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/import-mapping.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/import-mapping.md @@ -1,20 +1,33 @@ # Import Mapping -How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template. Never paste raw source into Mixpanel. +How to turn an arbitrary source document into template-conformant context. The source is *input*; the output is always the fixed template — per SKILL.md's "Imported content is mapped, never passed through raw" constraint. ## Mapping table (source → template section) -| If the source has… | Map to | -|---|---| -| "About us", company overview, what we do/sell | Business / Domain & Vocabulary | -| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | -| Definition of active/qualified/engaged user, MAU/WAU logic | Definition of Qualified User | -| Customer types, segments, personas, tiers | Customer Segments | -| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | -| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | -| Data owner, schema owner, "ask X before adding events", RACI | Authority & Governance | -| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | -| Default project guidance, which project for what | Conventions & Defaults (org) | +Section names are the literal `references/context-template.md` headings — use them verbatim, never a paraphrase. One annotation is allowed in Map-to cells: an "— bullet …" suffix names a bullet *inside* the section and is not part of the heading. ("(this project)" carries no such caveat — it *is* part of the literal project-level heading.) + +| If the source has… | Map to | Level | +|---|---|---| +| "About us", company overview, what we do/sell | Business | org | +| Product/surface description, what events represent, who the tracked end-user is | Domain & Vocabulary | project | +| North star, primary KPI, "the one metric", success criteria | North Star & Key Metrics | org | +| Definition of active/qualified/engaged user, MAU/WAU logic (org-wide) | North Star & Key Metrics — bullet "Definition of Active/Qualified User" | org | +| Definition of active/qualified/engaged user, MAU/WAU logic (project-specific override) | Definition of Active/Qualified User (this project) | project | +| Customer types, segments, personas, tiers | Customer Segments | org | +| Glossary, acronyms, "what we mean by X" | Internal Vocabulary & Acronyms | org | +| Default-project guidance, "which project for what", projects to avoid | Default Project & Routing | org | +| Tracking plan, event spec, naming rules, casing/prefix conventions | Event Taxonomy & Naming Conventions | project | +| Data owner, schema owner, "ask X before adding events" | Authority & Governance | project | +| List of canonical dashboards/reports and their purpose | Key Dashboards & Reports | project | + +Three template fields have no body section to map to. Two are filled by `import-context`'s "Fill gaps (mini-interview)" step (targeted questions for what the import left empty) instead of by import mapping: + +- The project `tldr;`'s "Why" line. +- The org `tldr;`'s "Who" line's internal-users clause (Customer Segments only covers external customer types). + +The third — the project `tldr;`'s "Where" line — is never mapped from a source doc: its integrations come from `schema_facts` (pulled live, see SKILL.md's session vocabulary), and the SDK/server/warehouse detail is confirmed via the Domain & Vocabulary "Where" question ("where does this project's data come from?") in `references/interview-questions.md`. + +`Open Questions` is never a direct mapping target either — it's populated via SKILL.md's "Ground everything" rule: anything the source can't ground lands there, not in a mapped section. Schema contradictions are one such case (see "What to drop"). ## What to drop (do not map) @@ -22,11 +35,10 @@ How to turn an arbitrary source document into template-conformant context. The s - Roadmap, upcoming features, "Q3 plans" — time-bound, not durable context. - Changelogs, migration notes, ticket references. - Anything that contradicts the live schema — flag it as an Open Question rather than importing it. -- Raw numbers/counts — schema facts come from the live pull, fenced and timestamped, not from the doc. +- Raw numbers/counts — barred by context-template.md's "no quantity-in-prose" rule; any live counts come from the schema pull, never from the doc. ## Rules -- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. +- **One concept per template section.** If the source mixes business intent and operational notes in one paragraph, extract only the durable business intent. E.g. from "activation is our north star, tracked on the growth pod's dashboard," map "activation" to North Star & Key Metrics and route the dashboard to Key Dashboards & Reports — don't paste the whole sentence into one section. - **Preserve the customer's own vocabulary.** If they call it "design partners" not "enterprise customers", keep their term — the agent should speak their language. - **Attribute nothing you can't ground.** If the doc implies an owner but doesn't name one, that's an Open Question, not an Authority entry. -- **Show your work.** The coverage view (import-context Step 3) must make clear which sections came from the source and which are still empty, so the user trusts the result and knows what the gap-interview will cover. diff --git a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/interview-questions.md b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/interview-questions.md index c30872d..5e99220 100644 --- a/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/interview-questions.md +++ b/plugins/mixpanel-mcp/skills/prepare-ai-readiness/references/interview-questions.md @@ -1,51 +1,56 @@ # Interview Questions -Starter question bank, grouped by template section. **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` where noted, ask in small batches. Unknown answers → Open Questions, never guessed. +Starter question bank, grouped by template section (`tldr;` and section names are defined in `references/context-template.md`). **Principle: never ask the customer what you can already find or fetch.** Research public facts first and present them to confirm; pull internal facts from their sources; only interview for what's genuinely internal and undocumented. Adapt wording per customer, seed with `schema_facts` (the live schema pull — see SKILL.md's session vocabulary) where noted, ask in small batches. Unknown answers go to Open Questions per SKILL.md's "Ground everything" rule. --- ## Before interviewing — research and pre-fill -Do these first, so the interview is mostly confirmation, not blank-filling: - -1. **Web search the company.** What it does, business model, customers/segments. Draft the **Business** and **Customer Segments** sections from public sources, then present for correction (see below). Don't ask these cold. -2. **Pull the schema** into `schema_facts` (top events, key properties) — needed to anchor the north-star and event questions to what actually exists in Mixpanel. -3. **Check for a definitions source.** Before asking vocab questions, ask if one exists and import it instead. +`commands/setup-context.md`'s "Research and pull schema first" step owns the pre-fill procedure — web-search the company to draft the Business and Customer Segments sections, and pull `schema_facts`. When that step has run (the `setup-context` path, with web search available), the interview is mostly confirmation, not blank-filling. When it hasn't — no web search tool, or the `import-context` gap-filling path — use each section's fallback question and ask directly. (Checking for a definitions source before vocabulary questions is handled by the Internal Vocabulary & Acronyms subsection, which is marked "ask for a source first.") --- -## ORG LEVEL +## Org level -### Business *(pre-filled from web search — confirm, don't ask)* +### Business *(confirm the web-research draft when one exists; else use the fallback)* - Here's what I found about the company: [drafted summary]. Is this right? Anything to fix or add? - Anything about the business model or how you make money that the public description gets wrong? - -### Customer Segments *(pre-filled from web search — confirm, don't ask)* -- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? +- *(Fallback, no pre-fill)* In a sentence or two: what does the company do, and how does it make money? ### North Star & Key Metrics *(must be Mixpanel-trackable)* -- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[Verified] Query Run`, activations, something else?") +- *(Seed with schema_facts)* Of the things you actually track in Mixpanel, which metric best reflects success? (anchor to real events, e.g. "is it `[X]`, activations, something else?") - What are the 2–3 supporting metrics **in Mixpanel** underneath it? -- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR, GMV in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. +- Is your true company north star something Mixpanel can't see? (e.g. revenue, NRR (net revenue retention), GMV (gross merchandise value) in a finance tool) If so, name it and the closest Mixpanel proxy — I'll note both so the agent doesn't chase data that isn't here. - How do you define an "active" or "qualified" user in this data? (the exact rule) -### Vocabulary & Acronyms *(ask for a source first)* +### Customer Segments *(confirm the web-research draft when one exists; else use the fallback)* +- I have these as your main customer types: [drafted list]. Accurate? Any segments you analyze separately that aren't obvious from outside? +- Which internal teams or roles use Mixpanel here (e.g. growth, product, support)? (feeds the org `tldr;`'s "Who" line — its internal-users clause) +- *(Fallback, no pre-fill)* What are your main customer types or segments, and what distinguishes them? + +### Default Project & Routing +- When someone asks a product question without naming a project, which project should the agent look in first? +- Which project answers which kind of question (e.g. web vs mobile, prod vs internal)? Any projects the agent should avoid (test, staging, sandbox)? + +### Internal Vocabulary & Acronyms *(ask for a source first)* - Do you have a glossary, data dictionary, or definitions page anywhere? If so, point me to it and I'll pull from it. - If not: what internal terms or acronyms would the agent misread? Term + meaning. (focus on words that mean something specific in *your* data — "activation", "engaged", "churned") --- -## PROJECT LEVEL +## Project level ### Domain & Vocabulary - What product or surface does this project track? (web app, mobile, backend, a specific feature) - Who is the end-user whose behavior shows up here? (your customer, an internal team, a machine/service) +- *(Seed with schema_facts' integrations)* Where does this project's data come from — client SDK, server-side, a warehouse import, or a mix? (confirms the schema-sourced "Where" line in the project `tldr;`) - *(Seed with schema_facts)* Your highest-volume events are `[X]` and `[Y]` — one line each, what do those represent? ### Event Taxonomy & Naming Conventions - How are events named here? Casing or prefix rules? (e.g. "Verb Noun", `[Verified]` prefix, snake_case) - *(Seed with schema_facts)* I see properties like `[A]` and `[B]` — what do they mean, and which matter most for analysis? - Any events or properties that look important but should be ignored? (test, deprecated, internal-only) +- How is analysis actually done here — custom entities or cohorts built on raw events, saved reports, conventions analysts follow? (feeds the project `tldr;`'s "How" line) ### Authority & Governance - Who owns the schema and the canonical reports in this project? @@ -56,10 +61,10 @@ Do these first, so the interview is mostly confirmation, not blank-filling: - Which dashboards/reports are the canonical, trusted ones? What is each for? - Where would you point a new team member first? -### Qualified User (this project) +### Definition of Active/Qualified User (this project) - Does "active" or "qualified" user mean something different here than at the org level? If so, what? -### Why / Business Impact +### Why (feeds the project `tldr;` — no dedicated body section) - What decisions does this project's analysis actually drive, and who acts on them? --- @@ -68,6 +73,11 @@ Do these first, so the interview is mostly confirmation, not blank-filling: Highest-value fields; source docs and web search usually lack them. Don't close an interview without them: -1. **Qualified/active user definition** — applied on almost every agent question. -2. **Authority** — who owns the schema and whose conventions to follow. Prevents the agent copying a random user's messy style. +1. **Active/qualified user definition** — applied on almost every agent question. +2. **Authority** — see the Authority & Governance questions; who owns the schema and whose conventions to follow, so the agent doesn't copy a random user's messy style. 3. **North star, scoped to Mixpanel** — anchored to events that exist here, with any out-of-Mixpanel true north star noted separately. +4. **Vocabulary** — see the Internal Vocabulary & Acronyms questions; check for a source before interviewing term-by-term. +5. **Why (project `tldr;`)** — see the Why question (Project level → Why). It's a tldr-only field with no body section, so `import-mapping.md` can't map it from a source doc — it must come from this list. +6. **Internal users (org `tldr;`)** — see the Customer Segments questions (Org level → Customer Segments; the internal-teams-and-roles bullet). Not covered by any external-facing source material, so `import-mapping.md` can't map it from a source doc either — it must come from this list. + +This is the canonical mandatory list — `commands/setup-context.md` and `commands/import-context.md` point here rather than restating it.