skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/data-analytics/pack.json

@@ -0,0 +1,57 @@
+{
+  "description": "For analysts and the people who rely on their numbers: define a metric once so everyone gets the same figure, review SQL for the bugs that quietly inflate it, and spec dashboards around a decision instead of every chart that was easy to make.",
+  "display_name": "Data and analytics",
+  "keywords": ["metrics", "sql", "dashboard", "semantic-layer", "dbt", "bi", "analytics"],
+  "links": {
+    "documentation": "https://sananthanarayan.github.io/skilldrop/packs/data-analytics/"
+  },
+  "maintainers": [
+    {
+      "name": "sananthanarayan"
+    }
+  ],
+  "first-value": {
+    "audience-posture": "technical",
+    "prerequisites": ["A SQL query whose number you need to trust, and the database it runs on"],
+    "starter-task": "Check a query before its number goes into a report",
+    "starter-prompt": "Review this Postgres query before it goes into the finance dashboard. One row per region; customers.customer_id is unique and an order has many order_items. Finance reports in New York time.\n\nSELECT c.region, SUM(o.amount_usd) AS revenue_usd\nFROM orders o\nJOIN customers c ON c.customer_id = o.customer_id\nJOIN order_items oi ON oi.order_id = o.order_id\nWHERE o.created_at BETWEEN '2026-09-01' AND '2026-09-30'\nGROUP BY c.region;",
+    "verification": "sql-review opens with a verdict, flags the order_items join as multiplying revenue and the BETWEEN as losing 30 September, gives a corrected query with New York boundaries, and lists verification queries to prove the fix.",
+    "recovery": "If the review jumps to indexes before correctness, ask for it by name (\"use sql-review\"). If it guesses the database, tell it which one: integer division and timezone functions differ between engines."
+  },
+  "requires": ["core"],
+  "journey": {
+    "when": "A number matters (a board metric, a finance figure, a team KPI) and people either disagree about it or are about to build a dashboard on it.",
+    "you_bring": [
+      "the metric name and the question it answers",
+      "the tables it comes from, and any SQL or dashboard already computing it",
+      "who reads it and what they decide",
+      "the database engine (Postgres, BigQuery, Snowflake, …)"
+    ],
+    "steps": [
+      {
+        "skill": "metric-definition",
+        "you_do": "Give it the metric, the sources, and any existing SQL.",
+        "you_get": "One written definition: exact formula, grain, window and timezone, exclusions with predicates, allowed dimensions, edge cases, owner, reference SQL and sanity checks.",
+        "decide": "Confirm the open decisions (timezone, exclusions, lock period) with the metric's owner."
+      },
+      {
+        "skill": "sql-review",
+        "you_do": "Run it on the definition's reference SQL, or on any query that already reports the number.",
+        "you_get": "A verdict and line-by-line findings, each with the wrong result and corrected SQL, plus the full corrected query and verification queries.",
+        "decide": "Certify the metric, or fix the SQL and review again."
+      },
+      {
+        "skill": "dashboard-spec",
+        "you_do": "Give it the audience, the decision and the list of requested charts.",
+        "you_get": "A one-page spec: questions in priority order, one chart per question built on your defined metrics, filters, freshness SLA, layout, and a cut list."
+      },
+      {
+        "skill": "doc-critique",
+        "you_do": "Run it on the metric spec or dashboard spec before sharing it with the BI team.",
+        "you_get": "A verdict and severity-tagged findings with a fix for each.",
+        "decide": "Hand the spec to the builder, or revise it."
+      }
+    ],
+    "you_end_with": "A certified metric definition with reviewed reference SQL, and a dashboard spec a BI developer can build without guessing."
+  }
+}

skilldrop_cli/data/packs/data-analytics/skills/dashboard-spec/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: dashboard-spec
+description: Spec a dashboard before anyone builds it — the audience and the decision it serves, the questions in priority order, one chart per question with the chart type and why, the defined metric behind each chart, filters, refresh cadence and freshness SLA, and a list of what is deliberately left off, with vanity metrics cut. Use when the user says "spec a dashboard", "what should go on our KPI dashboard", "the BI team needs requirements for a dashboard", "our dashboard has 40 charts and nobody uses it", or "design the exec dashboard".
+---
+
+# dashboard-spec
+
+Writes the one-page brief a BI developer builds from, so the dashboard answers the questions someone actually acts on instead of displaying every number that was easy to query. The spec starts from a decision, not from the available data: who looks at this, how often, and what they do differently depending on what they see. Every chart traces to a question, every question to that decision, and every metric to a written definition. What doesn't trace gets cut, and the cut list is part of the deliverable.
+
+## How to respond
+
+1. **Pin the audience and the decision, asking once.** Ask at most 2 questions in one message: *"Who opens this, and what do they decide or do after looking at it?"* and *"Which metrics already have agreed definitions, and where does the data live?"* If the user gave both, don't ask.
+
+**Non-interactive runs** (subagent, CI, headless): derive the audience and decision from the input and tag them `[assumption]`. A metric with no definition is marked `undefined` in the chart table, not invented. No audience and no decision derivable from the input → emit `BLOCKED: need the audience and the decision this dashboard serves`.
+
+2. **Write the decision statement in one sentence:** who, decides what, how often. ✅ *"Regional support leads decide each Monday which queues get extra staff this week."* — ❌ *"Give visibility into support performance."* If no decision can be named, say so plainly: what the user wants is a report or an archive, and the spec says that instead of designing charts nobody acts on.
+
+3. **List the questions in priority order, at most seven.** Each is a question the audience would ask out loud, paired with the action a bad answer triggers: ✅ *"Which queue is furthest over its response-time target this week? → move staff to it."* Question 1 is the reason the dashboard exists and goes top left. If you have more than seven, the dashboard serves more than one audience; split it.
+
+4. **Give each question exactly one chart, with its type and the reason.** Use the chooser in [`reference.md`](reference.md):
+   - change over time → line chart
+   - compare categories → bar chart, sorted, starting at zero
+   - one current value against a target → number tile with its comparison
+   - distribution → histogram or box plot
+   - relationship between two measures → scatter plot
+   - exact values someone looks up → table
+
+   ✅ *"Sorted horizontal bar, because the question is which queue is worst and a ranked bar answers that at a glance."* No pies for more than three parts, no dual axes, no 3D. Every number tile shows a comparison (against target, last period, or the same period last year). A bare number can't tell anyone whether to act.
+
+5. **Name the metric behind each chart by its `metric-definition` name**, with the grain, the time window and the comparison. ✅ `first_response_hours_p90` · daily · last 8 weeks · vs target 4h. A metric with no written definition is flagged `undefined: needs a spec before build`. That's a build blocker, not a detail for the BI developer to settle by guessing.
+
+6. **Set the filters**, at most four global ones with their default values. Only offer a filter on a dimension each affected metric can be sliced by. A filter that fans out a metric (product category on order-level revenue) is left off with a note saying why.
+
+7. **Set the refresh cadence and freshness SLA from the decision cadence.** A weekly decision needs a daily refresh at most; a live operations floor needs minutes. State the SLA (✅ *"data no older than 06:00 UTC each weekday"*), show a "data as of" timestamp on the dashboard, and say what happens when the data is stale: a visible banner, not a silently old chart. Don't pay for real-time on a weekly decision.
+
+8. **Write the cut list.** Every metric or chart someone asked for that didn't make it, with the reason. Run the vanity test on each candidate: *"If this number doubled tomorrow, what would the audience do differently?"* No answer → cut. Usual cuts: all-time cumulative totals (they only go up), page views and sessions with no outcome attached, any metric the audience can't influence, and duplicates of the same question in another chart type.
+
+9. **Sketch the layout** as a text grid: question 1's chart in the top row, supporting questions below, the detail table last. A reader from the audience should be able to answer question 1 from the top row without clicking anything.
+
+10. **Emit with [`templates/dashboard-spec.md`](templates/dashboard-spec.md)** in one message: decision statement, questions with actions, chart table, filters, refresh and freshness, layout grid, cut list, and open questions (undefined metrics, data gaps, unconfirmed owners).
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the chart chooser with when-not-to rules, the vanity-metric test with common cuts, and refresh cadence by decision type
+- [`templates/dashboard-spec.md`](templates/dashboard-spec.md) — the spec skeleton
+- [`examples/support-staffing.md`](examples/support-staffing.md) — worked example: a support dashboard request with 14 asked-for metrics, cut to five questions
+
+## Quality bar
+
+- **A one-sentence decision statement** names who decides what, and how often.
+- **At most seven questions, in priority order**, each with the action a bad answer triggers.
+- **One chart per question, with a type and a reason.** No chart without a question.
+- **Every chart names a metric by its defined name**, or flags it `undefined` as a build blocker.
+- **Every number tile carries a comparison.**
+- **Filters are four or fewer, have defaults, and never fan out a metric.**
+- **Refresh cadence matches the decision cadence**, with a freshness SLA and a visible stale-data behaviour.
+- **A cut list exists**, with a reason for each item, and vanity metrics are on it.
+- **Nothing is invented.** Metrics, targets and data sources not given are marked `[assumption]` or `undefined`.
+
+## When to use this skill
+
+- ✅ Before a BI developer or analyst builds a new dashboard
+- ✅ Rescuing a dashboard with too many charts that nobody opens
+- ✅ "What should be on our exec / ops / team KPI dashboard?"
+- ✅ Turning a list of requested metrics into a dashboard that serves one decision
+
+## When NOT to use this skill
+
+- ❌ Defining how one metric is calculated (formula, filters, timezone) — that's `metric-definition`
+- ❌ Choosing which metric judges a feature, with targets and a decision rule — that's `success-metrics`
+- ❌ Service health dashboards, SLOs and alerting — that's `observability-plan`
+- ❌ A report on AI tool usage from telemetry logs — that's `ai-usage-report`
+
+## Anti-patterns to avoid
+
+- ❌ **The data-first dashboard.** Starting from "what tables do we have" and charting all of them. Start from the decision.
+- ❌ **The 40-chart wall.** Built to look thorough, scanned by nobody, because no chart answers a question anyone asks.
+- ❌ **Bare number tiles.** "Revenue: $1.2M" with no target or prior period can't tell anyone whether to act.
+- ❌ **Pie charts with eight slices**, dual-axis charts and truncated bar axes. Each makes a comparison look different from what the data says.
+- ❌ **Undefined metrics handed to the builder.** The BI developer picks a filter and a timezone, and the dashboard disagrees with finance on day one.
+- ❌ **Real-time for a weekly meeting.** Paying for a live refresh that nobody looks at between Mondays.
+- ❌ **No cut list.** Every requested chart creeps back in at review because nobody wrote down why it was left out.
+- ❌ **Cumulative "growth" charts.** An all-time total only goes up, so it reads as success even while the business shrinks.

skilldrop_cli/data/packs/data-analytics/skills/dashboard-spec/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Spec a dashboard for our weekly ops review before the BI team builds it",
+    "should_trigger": true
+  },
+  {
+    "query": "What should go on the exec KPI dashboard? Here's the list everyone asked for",
+    "should_trigger": true
+  },
+  {
+    "query": "Our marketing dashboard has 40 charts and nobody uses it, redesign what goes on it",
+    "should_trigger": true
+  },
+  {
+    "query": "Write the requirements for a Looker dashboard for the finance team",
+    "should_trigger": true
+  },
+  {
+    "query": "Define exactly how monthly recurring revenue is calculated",
+    "should_trigger": false
+  },
+  {
+    "query": "Design SLOs, alerts and the service health dashboard for the payments API",
+    "should_trigger": false
+  },
+  {
+    "query": "Pick the success metrics and targets for the new search feature",
+    "should_trigger": false
+  },
+  {
+    "query": "Build a report of how my team is using AI coding tools from this usage log",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/data-analytics/skills/dashboard-spec/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "dashboard-spec",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Acme's VP of sales wants an exec dashboard for the Tuesday pipeline review, where she decides which deals need executive help and whether the quarter's forecast needs changing. Requested: total revenue all-time, pipeline by stage, win rate, average deal size, deals by rep, a leaderboard of calls made, website visitors, forecast vs quota, deals slipping past close date, and a map of customers. Defined metrics: `pipeline_value_usd` and `quarter_forecast_usd` (quota is $12M for the quarter). Data is in Salesforce, synced to BigQuery every 6 hours.",
+      "assertions": [
+        "Opens with a one-sentence decision statement naming the VP of sales, the Tuesday cadence, and both decisions (exec help on deals, forecast change)",
+        "Lists at most seven questions in priority order, each with the action a bad answer triggers",
+        "Gives each question one chart with a chart type and a one-line reason, and no chart without a question",
+        "References pipeline_value_usd and quarter_forecast_usd by name and flags win rate, deal size and slipping deals as undefined build blockers rather than inventing definitions",
+        "Shows forecast against the $12M quota as a comparison, not a bare number",
+        "Cuts total revenue all-time, the calls leaderboard, website visitors and the map, each with a reason",
+        "Sets a refresh and freshness SLA consistent with a weekly decision and the 6-hour sync, with stale-data behaviour",
+        "Does not invent targets, owners or metrics not given in the prompt; assumptions are tagged"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/data-analytics/skills/dashboard-spec/examples/support-staffing.md

@@ -0,0 +1,84 @@
+# Worked example: support staffing dashboard
+
+## Input
+
+> Northwind's support team wants a dashboard. The regional support leads meet every Monday at 09:00 London time to move agents between queues for the week. They've asked for: total tickets all-time, tickets this week, tickets by queue, tickets by channel, first-response time, resolution time, CSAT, backlog, agents online, tickets per agent, top 10 tags, website help-centre page views, NPS, and a world map of customers. Defined metrics so far: `first_response_hours_p90` (with a 4-hour target per queue) and `open_backlog_tickets`. Data is in the Zendesk export in Snowflake, refreshed nightly.
+
+No questions asked: the audience, the decision and its cadence, and the defined metrics are all in the prompt.
+
+## Output
+
+# Dashboard spec: Weekly queue staffing
+
+**Audience:** regional support leads · **Owner:** support operations lead `[assumption]` · **Tool:** not chosen
+**Decision:** Regional support leads decide every Monday which queues get more or fewer agents for the week.
+
+## Questions, in priority order
+
+| # | Question | If the answer is bad, they… |
+|---|---|---|
+| 1 | Which queues missed the 4-hour first-response target last week? | Move agents to those queues |
+| 2 | Which queues have the biggest open backlog going into this week? | Add agents or schedule a backlog session |
+| 3 | Is any queue's incoming volume trending up? | Plan staff ahead of the trend, not after it |
+| 4 | How many tickets does an agent on each queue handle per week? | Size the move: how many agents fix the gap |
+| 5 | Which queue and ticket combinations need a closer look? | Open the detail and assign follow-up |
+
+## Charts
+
+| # | Chart | Type | Why this type | Metric (defined name) | Grain · window · comparison |
+|---|---|---|---|---|---|
+| 1 | Which queues missed the 4h response target last week? | Sorted horizontal bar with a target line at 4h | Ranking against a threshold; the worst queue reads first | `first_response_hours_p90` | queue · last complete week · vs 4h target |
+| 2 | Open backlog by queue, Monday 06:00 | Sorted horizontal bar | Ranking by size | `open_backlog_tickets` | queue · snapshot · vs same time last week |
+| 3 | Incoming tickets per queue, last 8 weeks | Line chart, one line per queue (small multiples if more than five queues) | Change over time | `undefined: needs a spec before build` (incoming tickets: created time? merged tickets? spam?) | queue · weekly · last 8 weeks |
+| 4 | Tickets handled per agent-week by queue | Number tiles, one per queue | Single current value per queue, used for arithmetic | `undefined: needs a spec before build` (what counts as handled; how agent-weeks are counted for part-timers) | queue · last complete week · vs 4-week average |
+| 5 | Queue detail | Table, sorted by response time over target | Exact values for lookup | `first_response_hours_p90`, `open_backlog_tickets`, and the two undefined metrics | queue · last complete week |
+
+## Filters
+
+| Filter | Default | Applies to | Notes |
+|---|---|---|---|
+| Region | The viewer's region | All | |
+| Week | Last complete week (Monday to Sunday, London time) | Charts 1, 4, 5 | |
+
+Left off as filters: channel and tag. A ticket can carry several tags, so a tag filter would fan out the ticket counts; channel doesn't change a staffing decision made per queue.
+
+## Refresh and freshness
+
+- **Refresh:** nightly, matching the existing Snowflake load
+- **Freshness SLA:** Sunday's data loaded by 06:00 London time on Monday, three hours before the meeting
+- **When stale:** a red banner across the top naming the support operations lead
+- **"Data as of" timestamp:** top right, on every view
+
+## Layout
+
+```
++-----------------------------------------------------------+
+| Q1: Queues over 4h response target (sorted bar)           |
++-----------------------------+-----------------------------+
+| Q2: Open backlog by queue   | Q3: Incoming tickets trend  |
++-----------------------------+-----------------------------+
+| Q4: Tickets per agent-week tiles                          |
++-----------------------------------------------------------+
+| Q5: Queue detail table                                    |
++-----------------------------------------------------------+
+```
+
+## Deliberately left off
+
+| Requested item | Why it's cut |
+|---|---|
+| Total tickets all-time | Only goes up; changes no staffing decision |
+| Tickets this week (single total) | Replaced by the per-queue trend in chart 3, which tells the leads where to move people |
+| Tickets by channel | Staffing is by queue, not channel. Belongs on a channel-strategy dashboard. |
+| Resolution time | Driven by product fixes and customer replies as much as staffing. Keep it for the monthly quality review. |
+| CSAT, NPS | Lagging and not specific to a queue-staffing move this week. Monthly quality review. |
+| Agents online | A live-floor number; the decision is weekly |
+| Top 10 tags | Diagnostic, not a staffing input; tags also fan out counts |
+| Help-centre page views | Activity with no action for this audience |
+| World map of customers | Answers no question on the list |
+
+## Open questions
+
+- [ ] Incoming tickets needs a `metric-definition` spec (created time, merged and spam tickets). Owner: support operations lead.
+- [ ] Tickets handled per agent-week needs a spec (what "handled" means, part-time agents). Owner: support operations lead.
+- [ ] Confirm the dashboard owner.

skilldrop_cli/data/packs/data-analytics/skills/dashboard-spec/manifest.json

@@ -0,0 +1,40 @@
+{
+  "name": "dashboard-spec",
+  "version": "0.1.0",
+  "description": "Spec a dashboard before anyone builds it — the audience and the decision it serves, the questions in priority order, one chart per question with the chart type and why, the defined metric behind each chart, filters, refresh cadence and freshness SLA, and a list of what is deliberately left off, with vanity metrics cut. Use when the user says \"spec a dashboard\", \"what should go on our KPI dashboard\", \"the BI team needs requirements for a dashboard\", \"our dashboard has 40 charts and nobody uses it\", or \"design the exec dashboard\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "ai-usage-report",
+    "metric-definition",
+    "observability-plan",
+    "success-metrics"
+  ],
+  "handoff": [
+    {
+      "to": "metric-definition",
+      "when": "a chart's metric has no written definition",
+      "purpose": "Define the metric's formula, grain, window and exclusions so the BI developer doesn't guess.",
+      "fallback": "If metric-definition is absent, mark the metric undefined in the chart table and list the definitional questions (numerator, denominator, timezone, exclusions) under open questions."
+    }
+  ],
+  "tags": [
+    "dashboard",
+    "bi",
+    "analytics",
+    "kpi",
+    "data-visualization",
+    "requirements"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Structured spec from a decision and a metric list; the vanity-metric cut and chart choice need judgment but follow fixed rules."
+  }
+}

skilldrop_cli/data/packs/data-analytics/skills/dashboard-spec/reference.md

@@ -0,0 +1,45 @@
+# dashboard-spec reference
+
+## Chart chooser
+
+| The question asks… | Use | Don't use | Notes |
+|---|---|---|---|
+| How has it changed over time? | Line chart | Bar chart with 30+ bars, area chart for several overlapping series | Mark the target as a reference line. Label the last point. |
+| Which category is highest or lowest? | Horizontal bar, sorted | Pie, unsorted bars | Bars start at zero; a truncated axis exaggerates differences. |
+| Is the current value on target? | Number tile with comparison | Gauge, speedometer | Always show the comparison: vs target, vs last period, or both. |
+| How is a whole split, with three parts or fewer? | Stacked bar (100%), or a pie for two or three parts | Pie with more than three slices | People compare lengths more accurately than angles. |
+| How are values spread out? | Histogram, box plot | Average alone | An average hides the tail; show the spread or a percentile. |
+| Do two measures move together? | Scatter plot | Dual-axis line chart | Dual axes let the chart's author pick the apparent correlation. |
+| What is the exact value for a given item? | Table, sorted, with conditional formatting on the key column | A chart someone has to hover over | Put the table last; it's for lookup, not for the headline. |
+| Where did the change come from? | Bar of contributions (waterfall) | Two pies side by side | Use when the question is "why did it move". |
+
+General rules: one question per chart; the title states the question or the answer (✅ *"Queue B is 2.1h over target"* or *"Which queue is furthest over target?"*), not the metric name alone; no 3D; colour carries meaning (over target, under target) and is never the only cue.
+
+## The vanity test
+
+Ask of every candidate metric: **"If this number doubled tomorrow, what would the audience do differently?"** If nobody can name an action, cut it.
+
+Common cuts:
+
+- **All-time cumulative totals** (total registered users, lifetime orders). They only go up, so they read as success regardless of what's happening now.
+- **Activity without outcome** (page views, sessions, logins, emails sent). Keep only if paired with an outcome the audience owns.
+- **Metrics the audience can't move.** A regional lead can't act on global marketing spend.
+- **The same question twice**, in a different chart type or a slightly different metric.
+- **"Nice to know" context** that nobody checks. Put it on a linked detail page, not the main view.
+
+## Refresh cadence by decision type
+
+| Decision cadence | Refresh | Freshness SLA example |
+|---|---|---|
+| Live operations (support floor, incident) | Minutes | Data no older than 5 minutes |
+| Daily stand-up or daily ops | Daily, before the meeting | Refreshed by 07:00 in the team's timezone |
+| Weekly review | Daily | Refreshed by 06:00 on the review day |
+| Monthly or board reporting | Daily, with the month locked after close | Month figures final on the agreed close day |
+
+Every dashboard shows a "data as of" timestamp. When the freshness SLA is missed, the dashboard shows a visible stale-data banner and names the owner to contact. A chart that is silently a day old gets acted on as if it were current.
+
+## Filter rules
+
+- Four or fewer global filters, each with a default. More than that and every viewer sees a different dashboard.
+- A filter applies only where every affected metric can be sliced by that dimension (see each metric's allowed dimensions).
+- The date filter's default matches the decision: "last complete week" for a weekly review, not "last 7 days" ending mid-day today.

skilldrop_cli/data/packs/data-analytics/skills/dashboard-spec/templates/dashboard-spec.md

@@ -0,0 +1,55 @@
+# Dashboard spec: <dashboard name>
+
+**Audience:** <role(s)> · **Owner:** <role, team> · **Tool:** <BI tool, or "not chosen">
+**Decision:** <who> decides <what> <how often>, using this dashboard.
+
+## Questions, in priority order
+
+| # | Question | If the answer is bad, they… |
+|---|---|---|
+| 1 | <question the audience asks out loud> | <action> |
+| 2 | <...> | <...> |
+
+## Charts
+
+| # | Chart | Type | Why this type | Metric (defined name) | Grain · window · comparison |
+|---|---|---|---|---|---|
+| 1 | <title stating the question> | <line / sorted bar / number tile / table …> | <one line> | `<metric_name>` or `undefined: needs a spec before build` | <daily · last 8 weeks · vs target> |
+
+## Filters
+
+| Filter | Default | Applies to | Notes |
+|---|---|---|---|
+| <date range> | <last complete week> | <all> | |
+
+Left off as filters: <dimension> — <why, e.g. fans out order-level metrics>
+
+## Refresh and freshness
+
+- **Refresh:** <cadence>
+- **Freshness SLA:** <data no older than … by …>
+- **When stale:** <visible banner naming the owner>
+- **"Data as of" timestamp:** shown <where>
+
+## Layout
+
+```
++-----------------------------+-----------------------------+
+| Q1: <chart>                                               |
++-----------------------------+-----------------------------+
+| Q2: <chart>                 | Q3: <chart>                 |
++-----------------------------+-----------------------------+
+| Detail table                                              |
++-----------------------------------------------------------+
+```
+
+## Deliberately left off
+
+| Requested item | Why it's cut |
+|---|---|
+| <metric or chart> | <fails the vanity test / audience can't act on it / duplicates Q2 / belongs on another dashboard> |
+
+## Open questions
+
+- [ ] <undefined metric> — needs a `metric-definition` spec, owner <role>
+- [ ] <data gap or unconfirmed target>

skilldrop_cli/data/packs/data-analytics/skills/metric-definition/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: metric-definition
+description: Write a metric spec precise enough for a semantic layer or dbt metric to implement and for two analysts to get the same number — name, business question, exact numerator and denominator, grain, time window and timezone, filters and exclusions (test accounts, refunds), allowed dimensions, edge cases (NULLs, late data, currency), owner, reference SQL, and the sanity checks that catch it going wrong. Use when the user says "define this metric", "how exactly do we calculate X", "finance and product get different numbers for X", "write the metric spec for our semantic layer", or "what counts as an active user".
+---
+
+# metric-definition
+
+Turns a metric name that people already argue about ("active customers", "net revenue", "refund rate") into one written definition that produces one number. Most metric disputes are not about the data: they're two queries with different filters, windows or timezones answering under the same name. This skill pins every one of those choices down, writes the reference SQL, and adds the checks that catch the number drifting. It defines **how a metric is computed**. Choosing **which metric** judges a feature is `success-metrics`; that skill picks the primary, guardrails and decision rule, and this one makes any of those metrics exact.
+
+## How to respond
+
+1. **Pin the question and the sources, asking once.** Ask at most 2 questions in one message: *"What decision does this number inform, and who reads it?"* and *"Which tables or models hold the data, and is there SQL or a dashboard already computing something under this name?"* Existing SQL is the best input you can get: it shows the definition people actually use today, including its bugs. If the user gave both, don't ask.
+
+**Non-interactive runs** (subagent, CI, headless): derive the business question and sources from the input and tag each `[assumption]`. Choices the input doesn't settle (timezone, exclusions, late-data policy) get a stated default tagged `[assumption]` and are listed under open decisions. No metric name and no business question in the input → emit `BLOCKED: need the metric name and the question it answers`.
+
+2. **Name it so one name means one formula.** `snake_case`, noun phrase, qualified where variants exist: ✅ `net_revenue_usd`, `gross_revenue_usd` — ❌ `revenue` covering both. If two teams compute it differently and both versions are legitimate, they get two names, not one name with a footnote. State the business question in one sentence: ✅ *"What share of last month's orders were refunded, by region?"* — ❌ *"Track refunds."*
+
+3. **Write the exact formula.** Numerator and denominator, each in words and as an aggregation over named columns: ✅ *"Numerator: count of distinct `order_id` with at least one non-reversed refund. Denominator: count of distinct `order_id` created in the window."* Name the metric type (count, sum, distinct count, ratio, average, percentile, cumulative), the unit and the display format (%, USD, decimals). A ratio is always **ratio of sums**, never an average of per-row or per-day ratios. See [`reference.md`](reference.md) for the types and their traps.
+
+4. **Fix the grain and the time.** Write down:
+   - **Entity**: what one unit is (order, customer, account, session).
+   - **Time column**: which timestamp decides membership in a period (created, paid, shipped, event or load time) and why.
+   - **Window**: calendar month, ISO week (Monday start), rolling 28 days, trailing 7 complete days.
+   - **Timezone**: the reporting zone, with the IANA name, e.g. `America/New_York`, not "EST".
+   - **Partial periods**: whether the current period is shown, and how it's marked.
+   - **Additivity**: whether the metric can be summed across days, regions or segments. Distinct counts and ratios can't (four weekly active-user counts don't add up to monthly active users), so say how it rolls up: recompute from the base, don't sum.
+
+5. **List every filter and exclusion with its predicate and reason.** Always ask about the usual suspects: test and internal accounts, refunds and cancellations, fraud, deleted or merged records, free or zero-value transactions, and staff discounts. ✅ *"Exclude test accounts: `NOT EXISTS (SELECT 1 FROM test_accounts t WHERE t.customer_id = o.customer_id)`. Reason: QA places real orders in production."* An exclusion without a predicate gets implemented three different ways.
+
+6. **Name the dimensions it can be sliced by, and the ones it can't.** For each allowed dimension, give the source column, the join path and whether the join is one-to-one. A dimension that fans out (product category on order-level revenue, when an order has many categories) is either disallowed or comes with an allocation rule. Say which.
+
+7. **Settle the edge cases explicitly.** NULLs in each column the formula uses (counted, excluded or defaulted), zero denominators (show NULL, not 0), late-arriving data (how many days a closed period may still change, and when it locks), currency (rate source and which date's rate), DST days, duplicates and replays, backfills, and timezone changes. Each gets a one-line rule, not a "be careful".
+
+8. **Assign an owner and a change policy.** The owner is a role and a team (✅ *"Finance analytics lead"*), not "data team". Status: `draft` or `certified`. Changing the formula is a new version with a change log entry and a dated cutover, never a silent edit, because a silent edit breaks every trend line that crosses the change date.
+
+9. **Write the reference SQL** in the user's dialect: one CTE per step (base population, exclusions, numerator, denominator), half-open time windows (`>= start AND < end`), boundaries converted to the reporting timezone, and `NULLIF` on the denominator. The reference SQL is the tie-breaker when the prose and an implementation disagree. Recommend the user runs `sql-review` on it before it's certified.
+
+10. **Add the sanity checks** that would catch the metric being wrong, each runnable: reconciliation with a system of record (the finance ledger, the billing system), hard bounds (a rate stays within 0 to 1), additivity (regions sum to the total, for additive metrics only), join row counts (the base population's count doesn't change after dimension joins), a period-over-period alert threshold, and a hand-computed fixture of 5–10 rows with the expected answer.
+
+11. **Emit with [`templates/metric-spec.md`](templates/metric-spec.md)** in one message, ending with **open decisions**: each choice made by default, with the person who should confirm it.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — metric types and their traps, additivity rules, the exclusion and edge-case checklist, the sanity-check catalogue, and how the spec's fields map to a semantic layer (dbt MetricFlow and similar)
+- [`templates/metric-spec.md`](templates/metric-spec.md) — the spec skeleton
+- [`examples/refund-rate.md`](examples/refund-rate.md) — worked example: an order refund rate disputed between finance and support, defined end to end
+
+## Quality bar
+
+- **One name, one formula.** The numerator and denominator are written as aggregations over named columns, so two analysts would write the same SQL.
+- **Grain, time column, window and timezone are all explicit**, with an IANA timezone name and a half-open window.
+- **Every exclusion has a predicate and a reason.** No "exclude test data" without the SQL for it.
+- **Additivity is stated**, with the roll-up rule for non-additive metrics.
+- **Every allowed dimension has a join path and its cardinality**, and fan-out dimensions are disallowed or carry an allocation rule.
+- **Edge cases get one-line rules**, including late data with a lock date and zero denominators.
+- **The reference SQL runs as written** in the named dialect and matches the prose.
+- **At least three runnable sanity checks**, including one reconciliation with a system of record where one exists.
+- **Nothing is invented.** Table names, columns and business rules not given are marked `[assumption]` and listed in open decisions.
+
+## When to use this skill
+
+- ✅ Two teams report different numbers under the same metric name
+- ✅ Putting a metric into a semantic layer, dbt metrics or a BI tool's model, and it needs one definition
+- ✅ "What counts as an active user / a churned customer / net revenue?"
+- ✅ Certifying a metric before it goes on an exec dashboard or into a board pack
+
+## When NOT to use this skill
+
+- ❌ Choosing which metric judges a feature, with targets, guardrails and a decision rule — that's `success-metrics`
+- ❌ Checking that an existing query computes its number correctly — that's `sql-review`
+- ❌ Deciding which charts and metrics go on a dashboard — that's `dashboard-spec`
+- ❌ Agreeing a dataset's schema, freshness and quality guarantees with its consumers — that's `data-contract`
+- ❌ Service health indicators, SLOs and error budgets — that's `observability-plan`
+
+## Anti-patterns to avoid
+
+- ❌ **The footnoted metric.** One name, three formulas, and a footnote on each dashboard. Split it into named variants.
+- ❌ **Average of ratios.** `AVG(daily_refund_rate)` weights a quiet Sunday like Black Friday. Divide the sums.
+- ❌ **"Monthly" with no timezone.** The UTC month and the New York month differ by hours of orders at each boundary, and the number won't match finance's.
+- ❌ **Summing distinct counts.** Adding weekly active users to get monthly active users counts every returning user four times.
+- ❌ **Exclusions in prose only.** "Excludes test accounts" with no predicate gets implemented three different ways.
+- ❌ **Silent redefinition.** Changing the formula in place, so last quarter's trend line now compares two different metrics.
+- ❌ **No owner.** A metric "owned by the data team" is owned by nobody when finance and product disagree about it.
+- ❌ **Specs with no checks.** A definition that nobody tests drifts the first time an upstream table changes.

skilldrop_cli/data/packs/data-analytics/skills/metric-definition/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Define exactly how we calculate monthly active users so every dashboard agrees",
+    "should_trigger": true
+  },
+  {
+    "query": "Finance and product get different churn numbers. Write one definition with the SQL",
+    "should_trigger": true
+  },
+  {
+    "query": "Write the metric spec for net revenue for our dbt semantic layer",
+    "should_trigger": true
+  },
+  {
+    "query": "What should count as an active customer? Test accounts, refunds, timezone, all of it",
+    "should_trigger": true
+  },
+  {
+    "query": "How will we know the new onboarding flow worked? Pick the KPIs and targets",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a data contract for the events table other teams consume",
+    "should_trigger": false
+  },
+  {
+    "query": "Set SLOs and error budgets for the checkout API",
+    "should_trigger": false
+  },
+  {
+    "query": "Spec the executive sales dashboard before the BI team builds it",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/data-analytics/skills/metric-definition/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "metric-definition",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Product and sales at Northwind both report 'active customers' and the numbers never match. Product counts any account with a login in the last 30 days; sales counts accounts with a paid subscription. We use BigQuery: `analytics.logins` (account_id, login_ts TIMESTAMP), `billing.subscriptions` (account_id, status, plan, started_at, ended_at), and `crm.accounts` (account_id, segment, is_internal BOOL). Leadership wants one monthly number for the board, reported in London time. Write the definition.",
+      "assertions": [
+        "Splits the two meanings into separately named metrics (for example login-based and paid-subscription-based) instead of one name with a footnote, and states which one the board number uses or lists it as an open decision",
+        "Writes the formula as an aggregation over the named columns, using COUNT(DISTINCT account_id)",
+        "States the time column, a half-open window and the timezone as Europe/London",
+        "States that the metric is not additive and that monthly or segment values must be recomputed, not summed",
+        "Excludes internal accounts with an explicit predicate on crm.accounts.is_internal and gives a reason",
+        "Provides reference SQL in BigQuery syntax that converts the window boundaries to Europe/London",
+        "Includes at least three runnable sanity checks, including a known-answer fixture or a reconciliation with billing",
+        "Does not invent tables, columns or an owner not given in the prompt; anything assumed is tagged [assumption] and listed under open decisions"
+      ]
+    }
+  ]
+}