Skip to content

feat: add instrument-for-experiments skill#160

Draft
ceyniustranberg wants to merge 1 commit into
mainfrom
posthog-code/instrument-for-experiments-skill
Draft

feat: add instrument-for-experiments skill#160
ceyniustranberg wants to merge 1 commit into
mainfrom
posthog-code/instrument-for-experiments-skill

Conversation

@ceyniustranberg
Copy link
Copy Markdown

Summary

Adds an opinionated, experiment-driven instrumentation skill alongside the existing instrument-* omnibus skills.

Where instrument-product-analytics casts a wide net (10–15 events of generic business value), this skill scopes instrumentation to the events one specific experiment needs to be measurable:

  1. Hypothesis (BLOCKING) — testable, one sentence, three parts.
  2. Exactly one primary metric — mapped to a PostHog metric type (funnel/mean/ratio/retention).
  3. 1–3 secondary metrics — guardrails + mechanism, never used to declare victory alone.
  4. Inventory existing events via read-data-schema before adding anything new.
  5. Install + initialize PostHog (only if needed; defers to instrument-product-analytics references).
  6. Capture only the gaps — no "while we're here" events.
  7. Verification insight per metric so the user sees real data flowing before launching.
  8. Hand off to the experiment creation flow with hypothesis, metric spec, and proposed flag key.

Motivated by direct customer feedback (n8n): they explicitly do not want to instrument their codebase "for the sake of it" — they want a focused path from "we want to A/B test X" to "events flowing that let us measure X." The standard product-analytics sweep was the wrong shape for that audience.

What this PR does NOT do

  • Add example app code — it's a docs-only skill (workflow + best practices, not framework-specific snippets).
  • Touch the build pipeline, program registry, or wizard wiring — the build's filesystem scan picks the new directory up automatically; omnibus-instrument-for-experiments.zip appears in dist/skills/.
  • Duplicate instrument-product-analytics — it routes there for general coverage and to the PostHog MCP experiment creation skill for the actual experiment step.

Files

  • transformation-config/skills/omnibus/instrument-for-experiments/config.yaml — single-variant docs-only skill with 6 shared docs (experiments/metrics, experiments/best-practices, experiments/exposures, experiments/installation, product-analytics/capture-events, getting-started/identify-users).
  • transformation-config/skills/omnibus/instrument-for-experiments/description.md — the 10-step skill body with the {references} placeholder.

Test plan

  • pnpm test passes (60/60).
  • pnpm build discovers the new skill — omnibus-instrument-for-experiments.zip is emitted.
  • Unzipped bundle contains a well-formed SKILL.md with all 6 docs pulled into references/.
  • Reviewer sanity-check: are 1–2 of the docs URL choices worth swapping for something more specific (e.g. a dedicated funnels-vs-trends doc if one exists)?
  • Reviewer sanity-check on naming: instrument-for-experiments vs. e.g. instrument-experiment-metrics or scoping-experiment-instrumentation.

Context

Slack thread: Christophe ↔ Vincent, Friday 2026-05-29 — n8n engagement. Target was Monday 2026-06-01.

Adds an opinionated, experiment-driven instrumentation skill alongside the
existing `instrument-*` omnibus skills. Where `instrument-product-analytics`
casts a wide net (10–15 events of generic business value), this skill scopes
instrumentation to the events one specific experiment needs to be measurable:
hypothesis → one primary metric → 1–3 secondary metrics → inventory existing
events → capture only the gaps → verification insight → hand off to experiment
creation.

Motivated by direct customer feedback (n8n) that they do not want to instrument
their codebase "for the sake of it" — they want a focused path from "we want to
A/B test X" to "events flowing that let us measure X."

The skill renders into `omnibus-instrument-for-experiments.zip` via the
existing build pipeline; no registry or build script changes required. Pulls in
six PostHog docs as bundled references: experiments/metrics,
experiments/best-practices, experiments/exposures, experiments/installation,
product-analytics/capture-events, and getting-started/identify-users.

Generated-By: PostHog Code
Task-Id: 226e3d8f-099c-4322-8a72-538fc572895a
@github-actions
Copy link
Copy Markdown

🧙 Wizard CI

Run the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands:

Test all apps:

  • /wizard-ci all

Test all apps in a directory:

  • /wizard-ci basic-integration
  • /wizard-ci misc
  • /wizard-ci revenue

Test an individual app:

  • /wizard-ci basic-integration/android
  • /wizard-ci basic-integration/angular
  • /wizard-ci basic-integration/astro
Show more apps
  • /wizard-ci basic-integration/django
  • /wizard-ci basic-integration/fastapi
  • /wizard-ci basic-integration/flask
  • /wizard-ci basic-integration/javascript-node
  • /wizard-ci basic-integration/javascript-web
  • /wizard-ci basic-integration/laravel
  • /wizard-ci basic-integration/next-js
  • /wizard-ci basic-integration/nuxt
  • /wizard-ci basic-integration/python
  • /wizard-ci basic-integration/rails
  • /wizard-ci basic-integration/react-native
  • /wizard-ci basic-integration/react-router
  • /wizard-ci basic-integration/sveltekit
  • /wizard-ci basic-integration/swift
  • /wizard-ci basic-integration/tanstack-router
  • /wizard-ci basic-integration/tanstack-start
  • /wizard-ci basic-integration/vue
  • /wizard-ci misc/quack-quack
  • /wizard-ci revenue/stripe

Results will be posted here when complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant