{"id":11257,"plugin_id":"plugin_asdk_app_6a5e636eabcc8191b055490191e2a3ee","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:59:04.392Z","digest":"8facfd429aaec5294f36953e9c4933a8839265c741595228362dc8965ef7d407","against":null,"payload":{"name":"subtext-telemetry","description":"Workflow telemetry logging — record AI-reported workflow milestones (currently the onboarding flow) for funnel analysis. Use when executing an instrumented Subtext workflow and you need to log step-by-step progress events.","included_files":[],"skill_md_contents":"---\nname: subtext-telemetry\ndescription: Workflow telemetry logging — record AI-reported workflow milestones (currently the onboarding flow) for funnel analysis. Use when executing an instrumented Subtext workflow and you need to log step-by-step progress events.\n---\n\n# Telemetry\n\n> **PREREQUISITE:** Read `subtext-shared` for MCP conventions.\n\nThe telemetry tool records workflow milestones to Fullstory's analytics backend (BigQuery) for funnel analysis and success-rate dashboards. It writes analytics events only — it never modifies application data or org configuration.\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `telemetry-event` | Log one workflow milestone: a `workflow` + `step`, an optional `outcome`, and optional step-specific `metadata`. |\n\n## Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `workflow` | yes | Workflow name. Currently only `onboard` (the Subtext capture-snippet install flow) is supported. |\n| `step` | yes | Milestone within the workflow. For `onboard`, in order: `start`, `precheck`, `explore`, `plan`, `install`, `identify`, `link_analytics`, `mask_pii`, `complete`. |\n| `outcome` | no | `success`, `partial`, `fail`, or `skipped`. Omit for in-progress milestones. |\n| `metadata` | no | A JSON **object** (not an array or scalar) of step-specific fields — see below. |\n\n## Metadata fields by step\n\nEvery step's metadata may include `duration_ms` (int) and `tokens` (int). Additional fields vary by step:\n\n| Step | Extra fields |\n|------|--------------|\n| `start` | `harness` (string), `model` (string) |\n| `precheck` | `already_installed` (bool) |\n| `explore` | `framework` (string), `csp_present` (bool) |\n| `plan` | `approved` (bool) |\n| `install` | `framework` (string), `csp_modified` (bool) |\n| `identify` | `identity_added` (bool) |\n| `link_analytics` | `analytics_providers` (string[]) — names of every analytics / session-replay / error-monitoring / feature-flag SDK found installed, e.g. `[\"posthog\", \"segment\", \"sentry\"]` |\n| `mask_pii` | `masked_count` (int), `privacy_check` (bool) |\n| `complete` | `total_duration_ms` (int), `total_tokens` (int) |\n\nUnknown metadata fields are tolerated (ignored, not errors), but stick to the documented fields — only they land in typed columns for analysis.\n\n## Typical flow\n\nLog an event at each milestone as you execute the workflow, not retroactively at the end:\n\n```\ntelemetry-event workflow=\"onboard\" step=\"start\" metadata={\"harness\": \"claude-code\", \"model\": \"claude-fable-5\"}\n...\ntelemetry-event workflow=\"onboard\" step=\"install\" outcome=\"success\" metadata={\"framework\": \"nextjs\", \"csp_modified\": false, \"duration_ms\": 42000}\n...\ntelemetry-event workflow=\"onboard\" step=\"complete\" outcome=\"success\" metadata={\"total_duration_ms\": 310000, \"total_tokens\": 85000}\n```\n\nThe response is `{\"logged\": true}` on success or `{\"logged\": false, \"reason\": \"...\"}` on a soft failure.\n\n## Rules and constraints\n\n- **Fire-and-forget.** A `{\"logged\": false, ...}` response is a soft failure — note it and move on. Never retry in a loop, and never block or abort the user's workflow because telemetry failed.\n- Org and user identity are attached server-side from the authenticated MCP session — don't put emails, org IDs, or other identifying data in `metadata`.\n- Don't put secrets, tokens, file contents, or free-form user data in `metadata` — only the documented derived fields.\n- `outcome` is a classification of the step, not a log level: use `skipped` when a step didn't apply, `partial` when it half-worked, and omit it entirely for a step that's still in progress.\n- Only log events for workflows you are actually executing. The tool exists to measure real funnels — don't emit synthetic or exploratory events against a production org.\n\n## Gotchas\n\n- Passing `metadata` as anything other than a JSON object — arrays, strings, and scalars are rejected with `{\"logged\": false}`.\n- Inventing workflow or step names — only `onboard` and its nine documented steps are recognized. New workflows require backend support first.\n- Logging every step at the end of the workflow with made-up durations — log each milestone as it happens so `duration_ms` and failure points are real.\n- Treating a soft failure as an error worth surfacing to the user — telemetry is invisible plumbing; a failed event is at most a one-line note.\n\n## See Also\n\n- `subtext-shared` — MCP conventions\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}