Update to Data

{
  "name": "design-kpis",
  "description": "Design KPI frameworks, metric definitions, targets, guardrails, and measurement plans for product or business decisions. Use when success metrics, drivers, guardrails, targets, or the measurement approach need to be defined or improved.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 281
    }
  ],
  "skill_md_contents": "---\nname: design-kpis\ndescription: \"Design KPI frameworks, metric definitions, targets, guardrails, and measurement plans for product or business decisions. Use when success metrics, drivers, guardrails, targets, or the measurement approach need to be defined or improved.\"\n---\n\n# Design KPIs\n\nDesign KPI frameworks, set targets, and develop measurement plans that help teams make product or business decisions.\n\n## Overall Instructions\n\n- Follow the [shared Data instructions](../../shared/shared-skill-instructions.md) throughout this workflow.\n\n## Dependencies\n\nApply the shared [dependency resolution policy](../../shared/shared-skill-instructions.md#dependency-resolution) to the categories below.\n\n- Knowledge & Files: Goals, strategy, existing definitions, and measurement conventions.\n- Data Warehouse: Measured baselines and historical distributions for evaluating metrics and targets.\n- Business Intelligence: Existing scorecards, semantic definitions, and operating comparisons.\n- Product Analytics: Event instrumentation, behavioral measures, and experiment guardrails.\n- Internal Messaging: Ownership, operating practice, and discussions that point to canonical decisions.\n\n## When To Use Data Quality First\n\nUse $analyze-data-quality first when the task is to reconcile existing metrics, dashboards, tables, owners, or sources of truth.\n\nReturn to this skill only when the user asks to define the metric going forward, redesign the KPI framework, choose guardrails, or set targets.\n\n## Skill Configuration\n\n### Source Discovery And Verification\n\nUse the relevant data context as a starting map, not a boundary.\n\n1. **Find the authoritative evidence.** Follow references from discussions and summaries to the original metric, query, reporting view, or source artifact. Inspect relevant schemas, datasets, tables, views, models, and metrics when source discovery is needed. Known sources and semantic mappings are starting points; expand the search when stronger or complementary evidence could materially change the answer.\n2. **Compare duplicates and conflicts.** When sources overlap or disagree, compare ownership, freshness, definition, grain, coverage, and directness. Use the best authoritative source, or combine complementary sources when needed. Note material conflicts, explain why the selected sources control the answer, and verify the data through source reads or the explicitly supplied evidence.\n\n### Source Access Guardrail\n\nApply the shared [dependency resolution policy](../../shared/shared-skill-instructions.md#dependency-resolution) to identify required evidence, offer missing integrations, and continue supported work. Pause only claims or actions that depend on unavailable evidence; do not treat weaker substitutes as equivalent.\n\nClarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.\n\n## Workflow\n\n### 1. Clarify The Decision And Operating Context\n\nUnderstand the decision the metrics need to support, the context in which they will be reviewed, and who will act on the result. Ask the user to clarify the goal, operating cadence, or measurement constraints when missing or ambiguous input would change the recommendation.\n\n### 2. Gather Evidence Before Recommending Metrics\n\nWhen the prompt does not already provide enough context to know what success means, gather that context before recommending metrics or targets. Use $gather-business-context to understand the goal, current state, audience, constraints, risks, existing definitions, prior decisions, and any baseline or target context that should shape the metric system.\n\nFor KPI design, use that context to clarify what success is meant to mean, how related metrics have been defined before, and which constraints or risks should affect the recommended KPIs, drivers, guardrails, or measurement plan.\n\n### 3. Generate A Wider Candidate Set\n\nCreate candidate outcome, driver, and guardrail metrics before narrowing.\nEach candidate should have a clear definition and a plausible link to the decision. Use the example metric shapes below as inspiration when helpful, not as a required template.\n\n### 4. Compare And Select Metrics\n\nCompare candidate metrics by whether they:\n\n- reflect the goal: the metric should represent the intended outcome. When using a proxy, explain why it should reflect real progress and where it could mislead.\n- inform a real decision: movement should change what the team does, prioritizes, or investigates.\n- show useful signal at the decision cadence: a metric can be conceptually good but too slow-moving or noisy for the decision it supports. For example, annual retention may be the right outcome, but it may not help a weekly launch review unless paired with earlier indicators.\n- can be influenced by the team: the team should have plausible levers, or the metric should be paired with drivers it can affect.\n- can be measured operationally: the team should be able to instrument, calculate, and track the metric consistently without one-off manual work.\n- are hard to improve in a misleading way: improving the metric should not obviously hide harm to quality, trust, retention, cost, or another important outcome.\n\nUse lightweight scoring only when it helps explain tradeoffs. Recommend `1-3` primary KPIs, `1-2` driver metrics for each KPI when they improve diagnosis, and `1-2` guardrails when tradeoffs are likely. Do not recommend extra metrics unless they materially improve decision-making.\n\nFor each recommended metric, include enough detail for the team to use it: what it measures, why it matters, how it is calculated, where it comes from, its main pros and cons against the selection criteria above, and what caveats or guardrails matter.\n\n### 5. Set Targets When Needed\n\nTreat target setting as a separate judgment from metric selection. First decide what should be measured; then set targets when the user asks or when the recommendation needs a threshold to be useful.\n\nUse the target-setting approach that best fits the evidence:\n\n- Top-down: start from benchmarks, historical performance, comparable products, competitor or market context, or a reasoned view of what good would need to look like for the decision.\n- Bottom-up: start from what the team can realistically do, such as what is shipping, how adoption is expected to build, or which operating levers should move the metric.\n\nUse data to set or evaluate targets. Once the target-setting approach is clear, identify what data it requires, such as provided inputs, internal performance data, external benchmarks or market data, and results from similar past work.\n\nCompare aspirational targets with what the team can realistically influence through planned work, available audience, expected adoption, and historical movement. A good target should be meaningful for the decision and plausible enough to guide action. Explain the target anchor, key assumptions, and confidence. If the strongest target-setting method requires missing inputs, name the missing inputs and ask whether the user can provide or identify the relevant data. If there is still enough evidence for a directional target, present it as a provisional range; otherwise recommend the measurement needed before setting a firm target.\n\n### 6. Deliver The Recommendation\n\nFor source-backed Desktop inline answers outside Work Mode, include the [Sources receipt](../visualize-data/references/inline-sources-receipt.md), even when no chart is needed.\n\nKeep the final recommendation concise and decision-oriented. Use the response mode selected by the Data index. Pass chart-ready evidence to the selected response mode. Honor an explicitly requested report, dashboard, notebook, spreadsheet, native document, or slide deck as the primary artifact. The recommendation should include:\n\n1. initiative summary\n2. recommended metric candidates, with definition and rationale\n3. target recommendation, if included, with anchor and material assumptions\n4. evidence reviewed\n5. assumptions and missing context\n6. risks and guardrails\n7. open questions\n\n## Example Metric Shapes\n\nDifferent contexts need different metric shapes. Use these as examples, not a template:\n\n- Product launch or adoption: pair an outcome metric for adoption or value realization with drivers for activation, engagement, repeat use, or time to value, plus guardrails for experience quality.\n- Growth work: choose the business outcome the team is trying to improve, such as activation, retention, or monetization; add drivers that explain how growth is expected to happen and guardrails for quality.\n- Funnel work: choose the progression or completion outcome that represents success; add drivers around where people advance or drop off and guardrails for downstream quality.\n- Operating review: focus on health, pacing, and action-oriented metrics that show whether the business is on track and where attention is needed.\n- Experiment or intervention: use one primary success metric tied to the decision, diagnostics that explain movement, and guardrails for unintended effects.\n- Data, model, or analytics initiative: connect technical performance to the decision or workflow it improves, with adoption, reliability, cost, or fairness guardrails when relevant.\n- Platform, reliability, or operations work: measure service health, throughput, quality, cost efficiency, and customer impact in terms the owning team can act on.\n"
}