Update to aictrl.dev

{
  "name": "measurement-plan",
  "description": "Create a measurement plan for a feature using the Goal-Question-Metric (GQM) structure — defines a measurement goal, learning objectives, metrics, and implementation (product analytics events, warehouse tables, event pipeline). Use when user says 'measurement plan', 'GQM', 'goal question metric', 'goal-question-metric', 'measurement goal', 'how do we measure this', 'what metrics for this feature', 'tracking plan', 'analytics requirements', 'how do we know if this works', 'define KPIs for', or when planning a new feature and analytics instrumentation is needed.",
  "included_files": [],
  "skill_md_contents": "---\nname: measurement-plan\ndescription: Create a measurement plan for a feature using the Goal-Question-Metric (GQM) structure — defines a measurement goal, learning objectives, metrics, and implementation (product analytics events, warehouse tables, event pipeline). Use when user says 'measurement plan', 'GQM', 'goal question metric', 'goal-question-metric', 'measurement goal', 'how do we measure this', 'what metrics for this feature', 'tracking plan', 'analytics requirements', 'how do we know if this works', 'define KPIs for', or when planning a new feature and analytics instrumentation is needed.\n---\n\n# Measurement Plan\n\nCreate a structured measurement plan that connects business questions to metrics to implementation. The plan flows top-down:\n\n```\nGoal (what we're measuring & why — one templated statement)\n    ↓\nQuestions / Learning Objectives (what we need to learn to judge the goal)\n    ↓\nMetrics & Definitions (what to measure, linked to questions)\n    ↓\nImplementation Plan\n    ├── Product-analytics events (e.g. PostHog, Amplitude, Mixpanel)\n    ├── Warehouse / fact tables (e.g. BigQuery, Snowflake, Postgres)\n    └── Event pipeline (e.g. Pub/Sub, Kafka, Segment)\n```\n\n## Process\n\n### Phase 1: Goal\n\nBefore listing what you want to learn, state the measurement goal in one structured line. This is the GQM \"Goal\" level — it anchors every question and metric that follows. Fill these slots:\n\n- **Object** — what is being measured? (the feature / flow / process)\n- **Purpose** — why? (evaluate / improve / understand / predict)\n- **Quality focus** — which property? (adoption, reliability, speed, retention, cost…)\n- **Viewpoint** — for whom is this answered? (PM, end user, on-call engineer, finance…)\n- **Context** *(optional)* — scope/environment (which segment, plan tier, time window)\n\n**Goal statement:**\n> Analyze **<object>** for the purpose of **<purpose>** with respect to its **<quality focus>** from the viewpoint of **<viewpoint>**, in the context of **<context>**.\n\n**Example:**\n> Analyze **the bulk-import flow** for the purpose of **evaluating** its **adoption and reliability** from the viewpoint of **the product team**, in the context of **paid-tier orgs in the first 90 days**.\n\nA feature has 1–2 goals max (usually one feature goal; optionally one business goal). Get user approval on the goal before deriving questions.\n\n### Phase 2: Questions (Learning Objectives)\n\nBefore defining any metrics, establish what you need to learn. Each question must help judge the goal's quality focus from its viewpoint. There are two categories:\n\n**Feature Impact** — Does this feature achieve its goal?\n- Frame as hypotheses: \"We believe that [change] will result in [outcome] for [audience]\"\n- Or as questions: \"How does X affect Y?\"\n- These are specific to the feature being built\n\n**Business Performance** — How does this affect the broader business?\n- Upstream/downstream effects on key business metrics\n- Revenue, retention, adoption, engagement implications\n- Guard-rail metrics: things that should NOT get worse\n\nAsk the user:\n\n1. **What is the feature?** Brief description of what's being built.\n2. **What problem does it solve?** The user need or business case.\n3. **How will you know it worked?** What would success look like in 30/60/90 days?\n4. **What could go wrong?** Negative outcomes to watch for (guard-rail metrics).\n\nThen draft 3-6 learning objectives. Format:\n\n```markdown\n## Learning Objectives\n\n### Feature Impact\n- **Q1**: Does [feature] increase [desired outcome]?\n  - Hypothesis: [feature] will increase [metric] by [X]% within [timeframe]\n- **Q2**: Which user segment benefits most from [feature]?\n- **Q3**: What is the adoption curve — how quickly do users discover and use [feature]?\n\n### Business Performance\n- **Q4**: Does [feature] affect overall [business metric]? (e.g., retention, revenue)\n- **Q5**: Guard rail — does [feature] negatively impact [adjacent metric]?\n```\n\nValidate:\n- Every question traces to the goal; the goal's quality focus has at least one question.\n\nGet user approval before proceeding.\n\n### Phase 3: Metrics & Definitions\n\nFor each learning objective, define the metric(s) that answer it. Every metric needs:\n\n| Field | Description |\n|-------|-------------|\n| **ID** | M1, M2, M3... |\n| **Name** | Human-readable name |\n| **Definition** | Precise calculation (numerator/denominator for rates, aggregation for counts) |\n| **Answers** | Which learning objective(s) this addresses (Q1, Q2...) |\n| **Type** | `counter`, `rate`, `duration`, `ratio`, `funnel` |\n| **Granularity** | How often to compute (daily, weekly, per-event) |\n| **Segments** | Breakdowns needed (by org, by user, by plan tier, by source) |\n| **Data source** | Where the raw data comes from (your product-analytics tool / warehouse / billing system) |\n\nFormat as a table:\n\n```markdown\n## Metrics\n\n| ID | Metric | Definition | Answers | Type | Source |\n|----|--------|-----------|---------|------|--------|\n| M1 | Feature adoption rate | Users who used feature / Total active users (7d) | Q1, Q3 | rate | product analytics |\n| M2 | Time to first use | Median days from account creation to first feature use | Q3 | duration | warehouse |\n| M3 | Completion rate | Successful completions / Total attempts | Q1 | rate | warehouse |\n| M4 | Revenue per user (guard rail) | MRR / Active users, pre vs post launch | Q5 | ratio | billing system + product analytics |\n```\n\nValidate:\n- Every learning objective (Q) has at least one metric (M)\n- Every metric links to at least one question\n- No orphan metrics (metrics without a question are waste)\n- Guard-rail metrics are included\n\n### Phase 4: Implementation Plan\n\nFor each metric, define the data collection needed. Three layers:\n\n#### 3a. Product-Analytics Events (frontend/product analytics)\n\nFor user-facing interactions and product analytics. Tools like PostHog, Amplitude, or Mixpanel are the right choice when:\n- Tracking UI interactions (clicks, page views, form submissions)\n- Measuring user journeys and funnels\n- A/B test variant assignment and conversion\n- Session-level analysis\n\nFormat:\n\n```markdown\n### Product-Analytics Events\n\n| Event Name | Trigger | Properties | Metric |\n|------------|---------|------------|--------|\n| `feature_viewed` | User opens the feature page | `org_id`, `user_id`, `source` (sidebar/link/search) | M1, M3 |\n| `feature_action_completed` | User completes the core action | `org_id`, `user_id`, `duration_ms`, `result` | M3 |\n| `feature_error_shown` | Error state displayed | `org_id`, `error_type`, `step` | M3 |\n```\n\nNaming convention: `snake_case`, `object_action` pattern. Follow your tool's own conventions for past vs. present tense.\n\n#### 3b. Warehouse / Fact Table Changes (backend analytics)\n\nFor server-side events that need durable, queryable history. Use when:\n- The event happens on the server (not the browser)\n- You need immutable event history rather than mutable application state\n- Cross-referencing with other fact tables\n- The data feeds dashboards or scheduled reports\n\nName fact tables by domain (e.g. `execution_lifecycle`, `payment_events`). Determine:\n- **Existing table?** → Add a new `event_type` value (backward-compatible, no schema migration needed if you use a loose schema; coordinate with your data team if the table is strict)\n- **New table?** → Define schema + ingestion pipeline for your warehouse (Snowflake stage, BigQuery subscription, Postgres ETL job, etc.)\n\nFormat:\n\n```markdown\n### Warehouse Changes\n\n#### Additions to existing tables\n- Add `event_type: 'execution.retried'` to `execution_lifecycle` table\n  - New fields needed: `retry_count INT64`, `retry_reason STRING`\n\n#### New table (if needed)\n- Table: `{domain}_lifecycle` (name it by domain, not by tool or team)\n- Schema: define alongside your event pipeline setup\n```\n\nLink each change to the metric it supports.\n\n#### 3c. Event Pipeline Changes\n\nDerived from the warehouse changes above. For each new or modified fact table, document the pipeline event that feeds it:\n\n```markdown\n### Event Pipeline\n\n| Event Type | Stream/Topic | New/Existing | Fields | Metric |\n|------------|-------------|-------------|--------|--------|\n| `execution.retried` | execution-lifecycle | New event type on existing stream | `retry_count`, `retry_reason` | M3 |\n```\n\nFor new streams or topics, follow your pipeline tool's setup process (e.g. create a Kafka topic + consumer, a Pub/Sub subscription, or a Segment source).\n\n### Phase 5: Output Document\n\nProduce the measurement plan as a markdown file at `docs/measurement-plans/{feature-name}.md`:\n\n```markdown\n# Measurement Plan: {Feature Name}\n\n**Date:** {date}\n**Feature:** {brief description}\n**Owner:** {who is responsible}\n\n## 1. Goal\n\n> Analyze **<object>** for the purpose of **<purpose>** with respect to its **<quality focus>** from the viewpoint of **<viewpoint>**, in the context of **<context>**.\n\n## 2. Learning Objectives\n\n### Feature Impact\n- **Q1**: ...\n- **Q2**: ...\n\n### Business Performance\n- **Q3**: ...\n\n## 3. Metrics\n\n| ID | Metric | Definition | Answers | Type | Granularity | Source |\n|----|--------|-----------|---------|------|-------------|--------|\n| M1 | ... | ... | Q1 | rate | daily | product analytics |\n\n## 4. Implementation\n\n### 3a. Product-Analytics Events\n\n| Event | Trigger | Properties | Metric |\n|-------|---------|------------|--------|\n| ... | ... | ... | M1 |\n\n### 3b. Warehouse Changes\n\n...\n\n### 3c. Event Pipeline\n\n| Event Type | Stream/Topic | Status | Metric |\n|------------|-------------|--------|--------|\n| ... | ... | New | M1 |\n\n## 5. Validation\n\n### How to verify instrumentation\n- [ ] Goal is stated and every learning objective maps to it.\n- [ ] Product analytics: events visible in your tool's live-event stream within 24h of deploy\n- [ ] Warehouse: verify rows land in your fact table within 24h (query your table for recent rows)\n- [ ] Dashboard: metrics rendering correctly in your reporting tool\n\n### Review cadence\n- Week 1 post-launch: verify data flowing, fix instrumentation gaps\n- Week 4: first metrics review against hypotheses\n- Week 12: formal impact assessment\n```\n\n## Key Principles\n\n**Start with the goal, then questions, then data.** State the measurement goal first, derive questions from it, and only then choose metrics. If you can't articulate what you'll learn from a metric, don't track it. Every event must trace back to a learning objective, and every learning objective back to the goal.\n\n**Minimize instrumentation.** Fewer, well-defined events beat many sparse ones. Aim for 5-10 events per feature, not 50. Re-use existing events and properties where possible.\n\n**Layer appropriately.** Product analytics for frontend interactions, event pipeline → warehouse for server-side lifecycle events. Don't duplicate — if a server event already captures what you need, don't also track it in your product-analytics tool.\n\n**Plan for segments.** Every metric should be breakable by org, user role, and time period at minimum. Design properties to support this from day one — adding segments later requires re-instrumentation.\n\n**DRY naming across all layers.** Tables, streams, and events are namespaced by domain. Field/property/column names must NOT repeat the entity prefix. Use `version` not `skill_version`, `role` not `user_role`. The namespace provides context. This rule applies to product-analytics event properties, warehouse columns, pipeline event keys, and any application-state fields — all must use the same lean name to avoid mismatches between layers.\n\n---\n**Built by [aictrl.dev](https://aictrl.dev/?utm_source=oss-skills&utm_medium=skill&utm_campaign=measurement-plan&utm_listing=github-skills&utm_platform=portable&utm_skill=measurement-plan).** This skill teaches the workflow; aictrl *operationalizes* it — grounded in your backlog, team standards, and codebase knowledge graph. [See how →](https://aictrl.dev/features?utm_source=oss-skills&utm_medium=skill&utm_campaign=measurement-plan&utm_listing=github-skills&utm_platform=portable&utm_skill=measurement-plan)\n"
}