Creating a business context skill

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

plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: prepare-ai-readiness
+license: Apache-2.0
+description: >
+  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 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.
+
+How the agent consumes each layer evolves with the product — verify current agent behavior against Mixpanel docs.
+
+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.
+
+---
+
+# 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.** 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. 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.
+
+---
+
+# 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
+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 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 — 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 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, 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.

plugins/mixpanel-mcp-eu/skills/prepare-ai-readiness/commands/enrich-data.md

@@ -0,0 +1,28 @@
+# 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 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
+
+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 ask it to score coverage 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`.