skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/data-analytics/skills/metric-definition/examples/refund-rate.md

@@ -0,0 +1,104 @@
+# Worked example: order refund rate
+
+## Input
+
+> Finance says our September refund rate was one number and support says another. Can you write a proper definition? We're on Postgres. Orders are in `orders` (`order_id`, `customer_id`, `created_at` timestamptz, `amount_usd`), refunds in `refunds` (`refund_id`, `order_id`, `status`, `created_at`), and `test_accounts` lists QA customers. Finance reports monthly in New York time. Finance counts an order as refunded if any refund on it went through; support counts refund tickets. The finance analytics lead at Acme owns finance metrics.
+
+No questions asked: the decision (monthly finance reporting), the sources and the owner are all in the prompt. The dispute itself shows the two teams are measuring different things, so the spec splits them.
+
+## Output
+
+# Metric: `order_refund_rate` (v1, draft)
+
+**Business question:** What share of the orders placed in a month had at least one refund go through, by region? Read monthly by finance to track refund exposure.
+**Owner:** Finance analytics lead, Acme finance · **Status:** draft · **Last changed:** 2026-10-01
+
+**Why support's number differs:** support counts refund tickets, which is a different metric (`refund_tickets`, a count of tickets, not a share of orders). An order with two partial refunds is one refunded order here and two tickets there. Both are legitimate; they need separate names.
+
+## Formula
+
+| Part | In words | As an aggregation |
+|---|---|---|
+| Numerator | Orders in the window with at least one refund whose status is not `reversed` | `COUNT(DISTINCT o.order_id)` where a qualifying refund exists |
+| Denominator | Orders created in the window, excluding test accounts | `COUNT(DISTINCT o.order_id)` |
+
+- **Type:** ratio
+- **Unit and format:** %, 1 decimal
+
+## Grain and time
+
+- **Entity:** order
+- **Time column:** `orders.created_at`, so the refund is attributed to the month the order was placed. A September order refunded in October counts toward September.
+- **Window:** calendar month, half-open
+- **Timezone:** `America/New_York`
+- **Partial periods:** the current month is shown and labelled "month to date"
+- **Additivity:** not additive. A quarterly or all-region rate is recomputed from the base rows, never averaged from monthly or regional rates.
+
+## Filters and exclusions
+
+| Exclusion | Predicate | Reason |
+|---|---|---|
+| Test accounts | `NOT EXISTS (SELECT 1 FROM test_accounts t WHERE t.customer_id = o.customer_id)` | QA places real orders in production |
+| Reversed refunds | `r.status IS DISTINCT FROM 'reversed'` | A reversed refund returned no money |
+
+## Dimensions
+
+| Dimension | Source column | Join path | Cardinality | Allowed? |
+|---|---|---|---|---|
+| Region | `customers.region` | `orders.customer_id = customers.customer_id` | many-to-one `[assumption: customer_id unique]` | yes |
+| Product category | `order_items` → `products.category` | through `order_items` | one-to-many: fans out | no. An order with two categories would count in both. |
+
+## Edge cases
+
+| Case | Rule |
+|---|---|
+| Refund with NULL status | Counts as a refund `[assumption]` |
+| Zero orders in a region-month | Rate is NULL, shown blank |
+| Late data | Refunds arrive weeks after the order, so a month's rate keeps rising. The month locks for reporting 60 days after month end `[assumption]`; before that, label it "provisional". |
+| Currency | Not applicable: the metric counts orders, not money |
+| DST | Not applicable at month grain; boundaries are converted to New York time |
+| Duplicate refund rows | Handled: the numerator counts distinct orders |
+
+## Reference SQL (Postgres)
+
+```sql
+WITH base AS (                   -- orders placed in the month, no test accounts
+  SELECT o.order_id, o.customer_id
+  FROM orders o
+  WHERE o.created_at >= TIMESTAMP '2026-09-01' AT TIME ZONE 'America/New_York'
+    AND o.created_at <  TIMESTAMP '2026-10-01' AT TIME ZONE 'America/New_York'
+    AND NOT EXISTS (SELECT 1 FROM test_accounts t WHERE t.customer_id = o.customer_id)
+),
+refunded AS (                    -- one row per order with a qualifying refund
+  SELECT DISTINCT r.order_id
+  FROM refunds r
+  WHERE r.status IS DISTINCT FROM 'reversed'
+)
+SELECT
+  c.region,
+  COUNT(rf.order_id)::numeric / NULLIF(COUNT(*), 0) AS order_refund_rate
+FROM base b
+JOIN customers c      ON c.customer_id = b.customer_id
+LEFT JOIN refunded rf ON rf.order_id = b.order_id
+GROUP BY c.region;
+```
+
+## Sanity checks
+
+1. **Join integrity:** `SELECT COUNT(*) FROM base` equals the sum of per-region order counts from the query above with `COUNT(*)` added. If it's lower, orders without a matching customer are being dropped.
+2. **Bounds:** every region's rate is between 0 and 1, or NULL.
+3. **Customer key uniqueness:** `SELECT customer_id FROM customers GROUP BY customer_id HAVING COUNT(*) > 1` returns no rows.
+4. **Known-answer fixture:** five orders in September 2026 New York time: one with no refund, one with a single refund, one with two partial refunds, one with only a reversed refund, and one placed by a test account and refunded. Expected rate: 2 of 4 = 50.0%.
+
+## Change log
+
+| Version | Date | Change | Approved by |
+|---|---|---|---|
+| v1 | 2026-10-01 | Initial definition | pending: finance analytics lead |
+
+## Open decisions
+
+- [ ] Does a refund with NULL status count? Defaulted to yes. Confirm with the finance analytics lead.
+- [ ] Lock period of 60 days after month end. Confirm with the finance analytics lead against the refund policy window.
+- [ ] Is `customers.customer_id` unique? Check 3 answers it.
+- [ ] Support's `refund_tickets` metric needs its own spec, owned by support.

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

@@ -0,0 +1,41 @@
+{
+  "name": "metric-definition",
+  "version": "0.1.0",
+  "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\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "dashboard-spec",
+    "data-contract",
+    "observability-plan",
+    "sql-review",
+    "success-metrics"
+  ],
+  "handoff": [
+    {
+      "to": "sql-review",
+      "when": "the reference SQL is written and the metric is about to be certified",
+      "purpose": "Check the reference SQL for fan-out, NULL and timezone bugs before it becomes the tie-breaker.",
+      "fallback": "If sql-review is absent, run the spec's join-integrity and known-answer checks and note that the SQL has not been independently reviewed."
+    }
+  ],
+  "tags": [
+    "metrics",
+    "semantic-layer",
+    "dbt",
+    "analytics",
+    "data-quality",
+    "definitions"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Structured specification against a fixed checklist (formula, grain, window, exclusions, edge cases, checks). Needs care with SQL and additivity but no adversarial judgment."
+  }
+}

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

@@ -0,0 +1,67 @@
+# metric-definition reference
+
+## Metric types and their traps
+
+| Type | Example | Additive across time and dimensions? | Trap |
+|---|---|---|---|
+| Count | orders | Yes | Counting rows of a joined table instead of the entity |
+| Sum | revenue_usd | Yes, within one currency | Mixed currencies; refunds netted in some places and not others |
+| Distinct count | active_customers | **No** | Summing daily or regional counts double-counts entities present in several |
+| Ratio | refund_rate | **No** | Averaging per-day or per-segment ratios instead of dividing the sums |
+| Average | avg_order_value | **No** | It's a ratio (sum / count): roll up the parts, not the averages |
+| Percentile | p90_delivery_hours | **No** | Percentiles can't be combined; recompute from raw rows |
+| Cumulative | customers_to_date | No (it is a running total) | Restating history when late rows land in an old period |
+
+For every non-additive metric, the spec says: *"To roll up, recompute from the base rows; never sum or average the reported values."* A semantic layer that stores the numerator and denominator separately can roll up ratios correctly; one that stores only the ratio can't.
+
+## Exclusion checklist
+
+Ask about each. Every one that applies gets a predicate and a reason in the spec.
+
+- Test, QA, demo and internal/staff accounts
+- Refunds, chargebacks, cancellations and voids (and partial refunds)
+- Fraudulent or blocked transactions
+- Deleted, merged or anonymised records (including after a privacy erasure request)
+- Zero-value, free-tier or 100%-discount transactions
+- Duplicates from retries or event replays
+- Records outside the product's scope (wholesale orders, a sister brand)
+
+## Edge-case checklist
+
+| Case | The spec must say |
+|---|---|
+| NULL in a formula column | Counted, excluded, or defaulted, and to what |
+| Zero denominator | Show NULL (blank), not 0. 0% claims something happened. |
+| Late-arriving data | How many days a closed period may change; when it locks; whether restatements are announced |
+| Currency | Source of rates, which date's rate (transaction date or period end), and the reporting currency |
+| Timezone and DST | IANA zone name; what a "day" means on 23- and 25-hour days |
+| Week definition | ISO week (Monday start) or another start day, and how week 1 is numbered |
+| Backfills | Whether historical values change when a backfill runs, and who is told |
+| Definition change | New version number, change-log entry, cutover date; old version kept queryable for comparison |
+
+## Sanity-check catalogue
+
+Pick at least three. Each is written as a runnable query or test, not a description.
+
+1. **Reconciliation with a system of record.** The metric's total for a closed period matches the ledger, billing system or source report within a stated tolerance.
+2. **Bounds.** Rates within 0 and 1; counts not negative; revenue not negative unless refunds are netted.
+3. **Additivity.** For additive metrics only, the sum over a dimension equals the total. For distinct counts, the sum over a dimension is **at least** the total.
+4. **Join integrity.** Row count of the base population before and after each dimension join is equal.
+5. **Known-answer fixture.** 5–10 hand-built rows covering each exclusion and edge case, with the expected result worked out by hand. Run it in CI (a dbt unit test or a plain SQL assertion).
+6. **Period-over-period alert.** A change beyond a stated threshold (for example ±30% week over week) opens a ticket to check before anyone reports it.
+7. **Freshness.** The latest timestamp in the source is recent enough for the window being reported.
+
+## Mapping to a semantic layer
+
+Semantic layers differ in syntax but share the same parts. Map the spec's fields like this, then write the definition in your tool's own syntax and check it against that tool's documentation.
+
+| Spec field | Semantic layer concept |
+|---|---|
+| Entity | Primary entity or key of the model |
+| Time column and window | Aggregation time dimension and granularity |
+| Numerator, denominator | Measures (an aggregation plus an expression), combined in a ratio metric |
+| Filters and exclusions | A filter on the metric or measure, or exclusion done in the underlying model |
+| Allowed dimensions | Dimensions reachable through declared joins or entity relationships |
+| Owner, status, version | Metadata or `meta` fields, plus the repo's code owners |
+
+dbt's MetricFlow, for example, defines measures inside semantic models and offers simple, ratio, cumulative, derived and conversion metric types; a ratio metric there names a numerator metric and a denominator metric. Cube, LookML and other tools use their own terms for the same parts. Do the exclusions in the modelled table where you can, so every metric built on it inherits them, rather than repeating the filter in each metric.

skilldrop_cli/data/packs/data-analytics/skills/metric-definition/templates/metric-spec.md

@@ -0,0 +1,70 @@
+# Metric: `<metric_name>` (v<N>, <draft | certified>)
+
+**Business question:** <one sentence: what decision this number informs, and for whom>
+**Owner:** <role, team> · **Status:** <draft | certified> · **Last changed:** <YYYY-MM-DD>
+
+## Formula
+
+| Part | In words | As an aggregation |
+|---|---|---|
+| Numerator | <what is counted or summed> | `<COUNT(DISTINCT x) / SUM(y) ...>` |
+| Denominator | <population it is divided by, or "none"> | `<...>` |
+
+- **Type:** <count | sum | distinct count | ratio | average | percentile | cumulative>
+- **Unit and format:** <%, 1 decimal | USD, 0 decimals | count>
+
+## Grain and time
+
+- **Entity:** <order | customer | account | session>
+- **Time column:** `<table.column>`, because <why this timestamp and not another>
+- **Window:** <calendar month | ISO week | rolling 28 days | trailing 7 complete days>, half-open (`>= start AND < end`)
+- **Timezone:** `<IANA name>`
+- **Partial periods:** <shown and marked "to date" | hidden until complete>
+- **Additivity:** <additive across time and dimensions | not additive: recompute from base rows to roll up>
+
+## Filters and exclusions
+
+| Exclusion | Predicate | Reason |
+|---|---|---|
+| <test accounts> | `<SQL>` | <why> |
+
+## Dimensions
+
+| Dimension | Source column | Join path | Cardinality | Allowed? |
+|---|---|---|---|---|
+| <region> | `<customers.region>` | `<orders.customer_id = customers.customer_id>` | <many-to-one> | <yes> |
+| <product category> | `<...>` | `<...>` | <one-to-many: fans out> | <no, or allocation rule> |
+
+## Edge cases
+
+| Case | Rule |
+|---|---|
+| NULLs | <...> |
+| Zero denominator | <NULL, not 0> |
+| Late data | <closed period can change for N days; locks on day N+1> |
+| Currency | <rate source and date> |
+| Timezone and DST | <...> |
+| Duplicates | <...> |
+
+## Reference SQL (<dialect>)
+
+```sql
+-- base population, exclusions, numerator, denominator: one CTE each
+```
+
+## Sanity checks
+
+1. <reconciliation with system of record: query and tolerance>
+2. <bounds>
+3. <join integrity or additivity>
+4. <known-answer fixture>
+
+## Change log
+
+| Version | Date | Change | Approved by |
+|---|---|---|---|
+| v1 | <YYYY-MM-DD> | Initial definition | <owner> |
+
+## Open decisions
+
+- [ ] <choice made by default> — confirm with <role>

skilldrop_cli/data/packs/data-analytics/skills/sql-review/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: sql-review
+description: Review a SQL query for correctness first and performance second — join fan-out inflating sums, NULL traps in filters and NOT IN, timezone and date-boundary errors, integer division, DISTINCT hiding a bad join, window-frame defaults, implicit casts, non-sargable predicates and missing partition filters — with each finding tied to a line, the wrong number it produces, and corrected SQL for the named dialect. Use when the user pastes a query and asks "is this right", "review my SQL", "why is this number too high", "check this before it goes in the dashboard", or "make this query faster".
+---
+
+# sql-review
+
+Reviews a query the way a skeptical analyst would before trusting its output: first, does it return the right number; only then, does it return it cheaply. The failures this skill hunts are the silent ones — the query runs, returns a plausible figure, and is wrong by a factor of two because a join multiplied rows or a filter dropped NULLs. A slow correct query is an annoyance; a fast wrong one ends up in a board deck. The review is dialect-aware because the same SQL means different things in Postgres, BigQuery and Snowflake (integer division alone differs across them).
+
+## How to respond
+
+1. **Pin the dialect and the grain, asking once.** Ask at most 2 questions in one message: *"Which engine runs this (Postgres, BigQuery, Snowflake, Redshift, MySQL, SQL Server)?"* and *"What should one output row represent, and which join keys are unique?"* (for example: "one row per region; `customers.customer_id` is unique, `order_items` has many rows per order"). If the user already said, don't ask. Infer the dialect from syntax when you can — backtick-quoted `project.dataset.table` and `SAFE_DIVIDE` mean BigQuery, `::` casts mean Postgres, Redshift or Snowflake, `TOP n` means SQL Server — and state the inference.
+
+**Non-interactive runs** (subagent, CI, headless): infer the dialect from syntax and tag it `[assumption]`; with no syntax clue, review against the SQL standard and say which findings change by dialect. Assume join keys on dimension tables are unique and on fact or line-item tables are not, tag each such assumption, and turn it into a verification query. No query in the input → emit `BLOCKED: need the SQL query text`.
+
+2. **Run the lint for the mechanical layer.** It flags the smells regex can see — `= NULL`, `JOIN` with no `ON`, `NOT IN (SELECT …)`, `BETWEEN` on timestamps, `COUNT / COUNT` in dialects that truncate, `LAST_VALUE` without a frame, `LEFT JOIN` nullified by `WHERE`, `SELECT *`, `UNION` without `ALL`, functions on filtered columns:
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/sql_lint.py" query.sql --dialect postgres
+   # Other IDEs (from the skill folder)
+   python3 scripts/sql_lint.py query.sql --dialect postgres
+   ```
+
+   Use `-` to read from stdin, `--format json -o findings.json` for a file, and `--strict` to exit 1 on any error or warn. The lint does not parse SQL or know the schema. Treat each hit as a place to look: confirm it, or dismiss it in one line with the reason. A clean lint does not mean a correct query. Join fan-out, the most expensive bug, is invisible to it.
+
+3. **Review correctness by reading the query, in this order.** Walk the catalogue in [`reference.md`](reference.md):
+   1. **Grain.** For each `JOIN`, ask whether the right side can have more than one row per left row. If it can and the query sums a left-side column, the sum is multiplied. ✅ *"`order_items` has many rows per order, so `SUM(o.amount_usd)` counts each order once per item."* `COUNT(DISTINCT …)` next to a plain `SUM` is the classic tell: someone fixed the count and missed the sum.
+   2. **Filters and NULLs.** `NOT IN` with a nullable subquery, `col <> 'x'` silently dropping NULL rows, `WHERE` conditions on the outer side of a `LEFT JOIN`, `COUNT(col)` against `COUNT(*)`.
+   3. **Time.** Which timezone the date boundaries are in, whether the reporting window is half-open (`>= start AND < end`), whether `DATE()` or `date_trunc` runs in UTC or the session zone, and whether late-arriving rows belong in the window.
+   4. **Arithmetic and types.** Integer division, divide-by-zero, averaging averages (a mean of per-group ratios is not the overall ratio), implicit casts between strings and numbers, and currency mixed without conversion.
+   5. **Windows and set operations.** Default frames, ties in `ORDER BY` making `ROW_NUMBER` picks non-deterministic, `UNION` deduplicating rows that should both count.
+
+4. **Then performance, and only for a query that is already correct.** Look for non-sargable predicates, missing partition or cluster filters, `SELECT *` on columnar tables, correlated subqueries that run once per row, `ORDER BY` inside a CTE without a `LIMIT`, and `COUNT(DISTINCT)` where an approximate count would do. Name the cost model: bytes scanned in BigQuery, warehouse time in Snowflake, index use and the plan in Postgres. Tell the user to confirm with `EXPLAIN` or the bytes-billed estimate rather than assert a speed-up you did not measure.
+
+5. **Write every finding in four parts.**
+   - **Where:** line number and the quoted fragment.
+   - **Severity:** 🟥 wrong number today · 🟧 wrong number when certain data appears (a NULL, a tie, a DST day) · 🟨 cost or speed · ⚪ readability.
+   - **Wrong result:** the concrete effect on the output, in business terms. ✅ *"Revenue is overstated by the average number of items per order."* ❌ *"Possible duplication issue."* Don't invent magnitudes; if you can't compute the size, give the query that would.
+   - **Fix:** corrected SQL for that fragment, in the user's dialect.
+
+6. **Emit in one message:** a verdict line (`BLOCK`, `FIX FIRST`, `SHIP WITH NOTES`, `SHIP IT`) with the count by severity; the findings, correctness before performance; the **full corrected query**; and **2–4 verification queries** that prove the fix, such as row counts before and after each join, a reconciliation of the total against the source table, and a uniqueness check on each join key the fix depends on. List every assumption you made about keys and types.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the correctness and performance catalogue, each with the wrong result and the fix, plus a dialect table (integer division, divide-by-zero, timezone functions, window-frame defaults, partition pruning)
+- [`examples/revenue-by-region.md`](examples/revenue-by-region.md) — worked example: a Postgres revenue query with seven bugs, the lint's real output, the review, the corrected query, and the lint re-run
+- [`scripts/sql_lint.py`](scripts/sql_lint.py) — the mechanical-smell lint (stdlib, Python 3.9+)
+
+## Quality bar
+
+- **Correctness findings come before performance findings**, and a query with an open 🟥 is never given performance advice as its headline.
+- **Every finding names a line, the wrong result it produces, and corrected SQL.** A finding without a fix is a complaint.
+- **The wrong result is stated in business terms**, such as "refund rate always shows 0", not as "integer division issue".
+- **Fixes are in the user's dialect.** No `SAFE_DIVIDE` in a Postgres review, no `::numeric` in BigQuery.
+- **Join fan-out is checked for every join**, even when the lint is clean.
+- **A full corrected query is provided**, plus verification queries that would show whether the fix worked.
+- **Lint hits are triaged, not pasted.** Each one is confirmed or dismissed with a reason.
+- **Nothing about the schema is invented.** Key uniqueness, column types and timezones not given are listed as assumptions with a query to check each.
+
+## When to use this skill
+
+- ✅ "Is this query right?" before a number goes into a dashboard, report or deck
+- ✅ A metric looks too high or too low and the SQL is the suspect
+- ✅ Reviewing a teammate's analytics SQL or dbt model in a pull request
+- ✅ A correct query is too slow or too expensive and needs tuning
+
+## When NOT to use this skill
+
+- ❌ Deciding what a metric should mean (formula, filters, owner) — that's `metric-definition`; this skill checks that SQL computes it correctly
+- ❌ Designing tables, keys and indexes from access patterns — that's `db-schema-design`
+- ❌ Agreeing a dataset's schema, quality SLAs and change policy with its consumers — that's `data-contract`
+- ❌ General application code review, including SQL built in application code for security — that's `pre-merge-review`
+
+## Anti-patterns to avoid
+
+- ❌ **Performance first.** Suggesting an index for a query that double-counts revenue. Make it right, then make it fast.
+- ❌ **DISTINCT as the fix for duplicates.** Adding `DISTINCT` hides a fan-out in the row count but leaves every `SUM` computed before it inflated. Fix the join grain.
+- ❌ **Trusting a clean lint.** The lint can't see join cardinality, timezones or business rules. The worst bugs pass it.
+- ❌ **Vague findings.** "Watch out for NULLs" with no line and no wrong result. Name the row that disappears and why.
+- ❌ **Dialect-blind fixes.** Telling a BigQuery user to cast to `numeric` for division (BigQuery's `/` already returns FLOAT64), or a Postgres user that `/` on integers is safe.
+- ❌ **Asserting a speed-up.** "This will be 10x faster" without a plan or bytes estimate. Say what to measure.
+- ❌ **Rewriting the query in your own style.** Keep the user's structure and naming, and change only what the findings require, so the diff is reviewable.

skilldrop_cli/data/packs/data-analytics/skills/sql-review/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Is this SQL right? Revenue by region looks about double what finance has",
+    "should_trigger": true
+  },
+  {
+    "query": "Review my BigQuery query before I put it in the dashboard",
+    "should_trigger": true
+  },
+  {
+    "query": "Why does my refund rate come back as 0 in Postgres? Here's the query",
+    "should_trigger": true
+  },
+  {
+    "query": "This Snowflake query is correct but slow and expensive, can you tune it?",
+    "should_trigger": true
+  },
+  {
+    "query": "Design the tables and indexes for our new orders service",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a data contract for the orders table the finance team consumes",
+    "should_trigger": false
+  },
+  {
+    "query": "Define exactly how we calculate net revenue retention so everyone uses the same formula",
+    "should_trigger": false
+  },
+  {
+    "query": "Review this pull request to our Django app before merge",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/data-analytics/skills/sql-review/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "sql-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our Snowflake query for weekly active users per plan looks too high compared with the product dashboard. Can you review it?\n\nSELECT p.plan_name, DATE_TRUNC('week', e.event_ts) AS wk, COUNT(e.user_id) AS wau\nFROM events e\nJOIN subscriptions s ON s.user_id = e.user_id\nJOIN plans p ON p.plan_id = s.plan_id\nWHERE e.event_ts BETWEEN '2026-08-31' AND '2026-09-27'\n  AND e.user_id NOT IN (SELECT user_id FROM internal_users)\nGROUP BY 1, 2;\n\nsubscriptions keeps one row per plan change, so a user who upgraded has two rows. event_ts is TIMESTAMP_NTZ written in UTC. Acme reports weeks in UTC.",
+      "assertions": [
+        "Identifies that COUNT(e.user_id) counts events, not distinct users, so WAU is really weekly events",
+        "Identifies that the subscriptions join fans out for users with plan changes and attributes their events to every plan they ever had",
+        "Flags NOT IN against internal_users as returning no rows if that subquery contains a NULL, and proposes NOT EXISTS",
+        "Flags BETWEEN on event_ts as dropping 27 September after midnight and proposes a half-open window",
+        "Does not claim integer division is a problem, because there is no division and Snowflake's / returns a decimal anyway",
+        "Provides a full corrected query in Snowflake syntax that picks one plan per user per week (for example the plan active at the event time)",
+        "Provides verification queries, such as a uniqueness check on the subscription join and a reconciliation against a distinct-user count",
+        "Does not invent row counts or magnitudes not given in the prompt"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/data-analytics/skills/sql-review/examples/revenue-by-region.md

@@ -0,0 +1,174 @@
+# Worked example: September revenue and refund rate by region (Postgres)
+
+Shows the whole review: the lint as a first pass, the correctness findings the lint can't see, the corrected query, and the checks that prove it. The lint output below is the script's real output on these exact files.
+
+## Input
+
+> Can you check this before it goes into the finance dashboard? It's Postgres. Finance reports in New York time. One row per region. `customers.customer_id` is unique; an order has many `order_items`, and an order can have more than one refund row (partial refunds). `orders.created_at` is `timestamptz`.
+
+```sql
+-- September 2026 revenue and refund rate by region (finance reports in New York time)
+SELECT
+  c.region,
+  COUNT(DISTINCT o.order_id)              AS orders,
+  SUM(o.amount_usd)                       AS revenue_usd,
+  COUNT(r.refund_id) / COUNT(o.order_id)  AS refund_rate
+FROM orders o
+JOIN customers c     ON c.customer_id = o.customer_id
+JOIN order_items oi  ON oi.order_id = o.order_id
+LEFT JOIN refunds r  ON r.order_id = o.order_id
+WHERE o.created_at BETWEEN '2026-09-01' AND '2026-09-30'
+  AND r.status <> 'reversed'
+  AND o.customer_id NOT IN (SELECT customer_id FROM test_accounts)
+GROUP BY c.region
+ORDER BY revenue_usd DESC;
+```
+
+The user stated the dialect, grain and key uniqueness, so no questions are asked.
+
+## Step 2: lint
+
+```text
+$ python3 scripts/sql_lint.py query.sql --dialect postgres
+sql_lint: query.sql (dialect: postgres)
+
+line 6  WARN   integer-division
+    > COUNT(r.refund_id) / COUNT(o.order_id)  AS refund_rate
+    COUNT / COUNT in postgres: integer divided by integer truncates, so a 0.37 rate comes back as 0. Cast one side (::numeric, CAST(... AS DECIMAL), or * 1.0).
+
+line 11  WARN   between-timestamp
+    > WHERE o.created_at BETWEEN '2026-09-01' AND '2026-09-30'
+    BETWEEN on what looks like a timestamp column is inclusive at both ends. With a bare-date upper bound it drops everything after midnight on the last day; with a midnight upper bound it double-counts that instant across adjacent windows. Use col >= start AND col < next_day.
+
+line 12  WARN   left-join-where-filter
+    > AND r.status <> 'reversed'
+    WHERE filters on 'r', the right side of a LEFT JOIN. Rows with no match have NULL there and are dropped, so the LEFT JOIN behaves as an INNER JOIN. Move the condition into the ON clause if you meant to keep them.
+
+line 13  WARN   not-in-subquery
+    > AND o.customer_id NOT IN (SELECT customer_id FROM test_accounts)
+    NOT IN (subquery) returns zero rows if the subquery yields a single NULL. Use NOT EXISTS, or filter NULLs out of the subquery.
+
+4 finding(s): 0 error, 4 warn, 0 info
+```
+
+All four hits are confirmed below. The lint missed the two fan-outs and the timezone, which are the findings that matter most.
+
+## Output
+
+**Verdict: BLOCK — 5 🟥, 2 🟧, 0 🟨.** Every column in this query is wrong today. The `WHERE` on the refunds table keeps only refunded orders, two joins multiply revenue, and the month boundaries are in the wrong timezone and miss 30 September.
+
+### 🟥 1. `order_items` join multiplies revenue (line 9)
+
+- **Where:** `JOIN order_items oi ON oi.order_id = o.order_id`
+- **Wrong result:** each order appears once per line item, so `SUM(o.amount_usd)` counts a three-item order three times. Revenue is overstated by the average items per order. `COUNT(DISTINCT o.order_id)` on line 4 hides this in the order count, which is why the revenue looked plausible next to it. No column from `oi` is used.
+- **Fix:** delete the join.
+
+### 🟥 2. `refunds` join multiplies revenue again (line 10)
+
+- **Where:** `LEFT JOIN refunds r ON r.order_id = o.order_id`
+- **Wrong result:** an order with two partial refunds appears twice, on top of finding 1.
+- **Fix:** reduce refunds to one row per order before joining:
+  ```sql
+  refunded AS (
+    SELECT DISTINCT r.order_id
+    FROM refunds r
+    WHERE r.status IS DISTINCT FROM 'reversed'
+  )
+  ```
+  (`DISTINCT` here sets the grain of a single-table CTE, which is the right use; it isn't hiding a join.)
+
+### 🟥 3. `WHERE r.status` turns the LEFT JOIN into an INNER JOIN (line 12)
+
+- **Where:** `AND r.status <> 'reversed'`
+- **Wrong result:** orders with no refund have `r.status` NULL, the comparison is unknown, and they are dropped. The query reports revenue for **refunded orders only**. It also drops refunds whose status is NULL.
+- **Fix:** move the condition into the refunds CTE above, using `IS DISTINCT FROM` so NULL-status refunds still count. Whether a NULL status counts as a refund is a business rule: confirm it with finance.
+
+### 🟥 4. Refund rate is integer division (line 6)
+
+- **Where:** `COUNT(r.refund_id) / COUNT(o.order_id)`
+- **Wrong result:** in Postgres, `bigint / bigint` truncates. As written, finding 3 means every surviving row has a refund, so the rate returns 1 for every region. Fix finding 3 alone and it returns 0 for every region. Both counts are also inflated by findings 1 and 2.
+- **Fix:** `COUNT(rf.order_id)::numeric / NULLIF(COUNT(*), 0)`, counted at order grain.
+
+### 🟥 5. `BETWEEN` loses 30 September (line 11)
+
+- **Where:** `o.created_at BETWEEN '2026-09-01' AND '2026-09-30'`
+- **Wrong result:** the upper bound is midnight at the start of 30 September, so the last day of the month is missing.
+- **Fix:** half-open window, `>= start AND < next month start` (combined with finding 6).
+
+### 🟧 6. Month boundaries are in the session timezone, not New York (line 11)
+
+- **Where:** the same predicate.
+- **Wrong result:** the string literals are read in the session's `TimeZone`. On a UTC server, the window starts and ends four hours away from the New York boundaries (EDT in September), moving orders between August, September and October. The numbers won't match finance's.
+- **Fix:** convert the boundaries, not the column, so the predicate stays sargable:
+  ```sql
+  o.created_at >= TIMESTAMP '2026-09-01' AT TIME ZONE 'America/New_York'
+  AND o.created_at <  TIMESTAMP '2026-10-01' AT TIME ZONE 'America/New_York'
+  ```
+
+### 🟧 7. `NOT IN` returns nothing if `test_accounts` ever holds a NULL (line 13)
+
+- **Where:** `o.customer_id NOT IN (SELECT customer_id FROM test_accounts)`
+- **Wrong result:** correct today only if `test_accounts.customer_id` has no NULLs. One NULL row and the dashboard shows zero orders everywhere.
+- **Fix:** `NOT EXISTS (SELECT 1 FROM test_accounts t WHERE t.customer_id = o.customer_id)`.
+
+### Corrected query
+
+```sql
+WITH sept_orders AS (            -- one row per order
+  SELECT o.order_id, o.customer_id, o.amount_usd
+  FROM orders o
+  WHERE o.created_at >= TIMESTAMP '2026-09-01' AT TIME ZONE 'America/New_York'
+    AND o.created_at <  TIMESTAMP '2026-10-01' AT TIME ZONE 'America/New_York'
+    AND NOT EXISTS (
+      SELECT 1 FROM test_accounts t WHERE t.customer_id = o.customer_id
+    )
+),
+refunded AS (                    -- one row per refunded order
+  SELECT DISTINCT r.order_id
+  FROM refunds r
+  WHERE r.status IS DISTINCT FROM 'reversed'
+)
+SELECT
+  c.region,
+  COUNT(*)                                           AS orders,
+  SUM(so.amount_usd)                                 AS revenue_usd,
+  COUNT(rf.order_id)::numeric / NULLIF(COUNT(*), 0)  AS refund_rate
+FROM sept_orders so
+JOIN customers c      ON c.customer_id = so.customer_id
+LEFT JOIN refunded rf ON rf.order_id = so.order_id
+GROUP BY c.region
+ORDER BY revenue_usd DESC;
+```
+
+Lint re-run on the corrected query (real output):
+
+```text
+$ python3 scripts/sql_lint.py query-fixed.sql --dialect postgres
+sql_lint: query-fixed.sql (dialect: postgres)
+
+No mechanical smells found. This does not mean the query is correct;
+review joins, grain and date boundaries by reading it.
+```
+
+### Verification queries
+
+1. **Revenue reconciles with the source.** The sum of `revenue_usd` across regions should equal:
+   ```sql
+   SELECT SUM(amount_usd) FROM orders o
+   WHERE o.created_at >= TIMESTAMP '2026-09-01' AT TIME ZONE 'America/New_York'
+     AND o.created_at <  TIMESTAMP '2026-10-01' AT TIME ZONE 'America/New_York'
+     AND NOT EXISTS (SELECT 1 FROM test_accounts t WHERE t.customer_id = o.customer_id);
+   ```
+   If the region total is lower, some orders have no matching customer and the inner join dropped them.
+2. **The customer key really is unique** (the fix depends on it):
+   ```sql
+   SELECT customer_id, COUNT(*) FROM customers GROUP BY customer_id HAVING COUNT(*) > 1 LIMIT 10;
+   ```
+3. **Sum of `orders` equals the row count of `sept_orders`**, which proves the joins kept one row per order.
+
+### Assumptions
+
+- `customers.customer_id` is unique (stated by the user; check 2 confirms it).
+- A refund with a NULL status counts as a refund. Confirm with finance.
+- `amount_usd` is already in USD for every order.
+- "September" means order creation time, not payment or ship time.

skilldrop_cli/data/packs/data-analytics/skills/sql-review/manifest.json

@@ -0,0 +1,42 @@
+{
+  "name": "sql-review",
+  "version": "0.1.0",
+  "description": "Review a SQL query for correctness first and performance second — join fan-out inflating sums, NULL traps in filters and NOT IN, timezone and date-boundary errors, integer division, DISTINCT hiding a bad join, window-frame defaults, implicit casts, non-sargable predicates and missing partition filters — with each finding tied to a line, the wrong number it produces, and corrected SQL for the named dialect. Use when the user pastes a query and asks \"is this right\", \"review my SQL\", \"why is this number too high\", \"check this before it goes in the dashboard\", or \"make this query faster\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "data-contract",
+    "db-schema-design",
+    "metric-definition",
+    "pre-merge-review"
+  ],
+  "handoff": [
+    {
+      "to": "metric-definition",
+      "when": "the review finds the query's filters or formula disagree with what the business means, and no written definition exists",
+      "purpose": "Agree the metric's formula, grain, window and exclusions before fixing the SQL to match.",
+      "fallback": "If metric-definition is absent, list the definitional questions (numerator, denominator, timezone, exclusions) in the review's assumptions and mark the affected findings as pending a decision."
+    }
+  ],
+  "tags": [
+    "sql",
+    "analytics",
+    "data-quality",
+    "code-review",
+    "postgres",
+    "bigquery",
+    "snowflake"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
+  "model": {
+    "tier": "heavy",
+    "rationale": "Adversarial correctness review: finding join fan-out, NULL and timezone bugs means reasoning about data the query never shows, and a missed finding ships a wrong number. Never downgrade."
+  }
+}