@malloy-publisher/skills 0.1.0

package/skills/malloy-review/reference/output-template.md

@@ -0,0 +1,164 @@
+# Review Results File: Template & Assembly Rules
+
+The output of `/malloy-review` is a single Markdown file, written to `./malloy-review-<YYYYMMDD-HHMMSS>.md` unless `--out` overrides. The file is designed as a **triage document**: the user scans the top, expands only what they want, and can treat the JSON tail as a work-queue.
+
+## Canonical skeleton
+
+```md
+# Malloy Model Review: <one-line scope summary>
+<branch or path> · <package(s)> · <N files, M lines> · <timestamp>
+
+## Scope
+- **Reviewed:** <explicit list of folders/files/globs>
+- **Package(s):** <publisher.json packages covered, or "no publisher.json, reviewed folder only">
+- **Excluded:** <anything skipped, and why (generated dirs, fixtures, files outside the positional path)>
+- **IDE diagnostics:** available for X of Y files (<list of files WITH diagnostics>); Z files had no diagnostics (<list or "most of the scope">, likely unopened in the IDE). Open and re-run for fuller compiler coverage on those files.
+
+## Executive Summary
+<3–5 sentences: reconstructed intent of the model/change, what's working, the top 1–3 problems.>
+
+- **Recommendation:** <Approve · Approve-with-comments · Request-changes · Recommend-split>
+- **Coverage honesty:** <X files deep-reviewed, Y sampled, Z skimmed, and the rationale for each tier.>
+- **Top risks:** <one-line list referencing finding IDs, e.g. "B1 (silent cardinality bug), C2 (governance regression), D-series (docs drift on public measures).">
+
+## Coverage & Risk Map
+| File | LOC | Risk | Depth | Notes |
+|---|---:|---|---|---|
+| models/finance/revenue.malloy | 412 | HIGH | DEEP | New public measures; cardinality change |
+| models/shared/_joins.malloy | 180 | HIGH | DEEP | PK hygiene, new `join_one:` |
+| models/marketing/attrib.malloy | 2,300 | MED | SAMPLE | Bulk rename; representative sample reviewed |
+| tests/fixtures/*.malloy | 600 | LOW | SKIM | Generated; smoke-check only |
+
+Risk formula: `(touches join|PK|access) × LOC × public-surface-membership × (#diagnostics available)`. Depth is the review response, not the risk itself: DEEP = line-by-line, SAMPLE = N% plus hot paths, SKIM = smell-check only.
+
+## Cross-Cutting Themes
+<3–5 systemic observations that only a multi-dimension review can surface. Each theme cites finding IDs.>
+
+1. **Join cardinality hygiene regression:** three new `join_one:` declarations lack matching `primary_key:` on the target source (see B1, B2, B3). Systemic fix recommended over per-site patches.
+2. **Documentation coverage dropped on public measures:** 91% → 74% after this change. Affected fields listed in D-series findings.
+3. **Access-modifier gap:** nine new measures are implicitly `public` with no `#(doc)`; the governance reviewer recommends explicit annotation (G1–G9).
+
+## Top Issues (Blockers & Criticals)
+
+<Each entry uses this layout. List all blockers first, then all criticals. No majors/minors here, those go in Detailed Findings.>
+
+- **B1** `issue (blocking, correctness-join)` · `models/finance/revenue.malloy:142` · conf 95
+  - **Rule:** Declared `primary_key:` is not unique in the data
+  - **Current:** `join_one: customers on customer_id = customers.id`; the `customers.id` column has duplicates (verified: `pk_verified=false` from SKILL.md step 3).
+  - **Why it matters:** Malloy's symmetric-aggregation SQL relies on the declared PK being unique. When it isn't, the `DISTINCT` step collapses what shouldn't and aggregations across this join return hash-collision-sized garbage (~10²¹).
+  - **Suggested fix:** Pick a different / composite PK that IS unique, OR add a source-level `where:` that scopes `customers` to a uniquely-keyed subset, OR declare a `#(filter) ... required` annotation so consumers must supply the discriminating filter.
+  - **Source:** rubric-correctness.md (rule C-12); pk_verified=false from SKILL.md step 3.
+
+## Detailed Findings by File
+
+<Collapsed per file. Within each file, group by dimension. Each finding uses the short form below.>
+
+<details>
+<summary><code>models/finance/revenue.malloy</code>, 4 findings (1 blocker, 2 major, 1 minor)</summary>
+
+- **B1** (correctness-join, conf 95) line 142, see Top Issues
+- **D3** (docs major, conf 88) line 67, `#(doc)` missing on public measure `monthly_revenue`. Fix: add a one-line business description above the measure.
+- **R2** (rendering major, conf 95) line 89, Fixed scale (`# currency=usd0m`) on measure definition. Fix: move the scale to the view and leave `# currency` on the definition.
+- **D4** (docs minor, conf 82) line 71, `#(doc)` uses Malloy jargon ("aggregation of total revenue"). Fix: describe business meaning and units, e.g. `#(doc) Total revenue from completed orders in USD`.
+
+</details>
+
+<details>
+<summary><code>models/shared/_joins.malloy</code>, 3 findings</summary>
+...
+</details>
+
+## Questions for the Author
+<Understanding gaps, things the review couldn't resolve without more context. One per bullet, each anchored to a file/line.>
+
+- `models/finance/revenue.malloy:142`, is `customers.id` actually unique per customer? The CRM import documented in `modeling-notes.md` suggests duplicates on re-runs.
+- `models/shared/users.malloy:12`, new source-level `where: project_id = @session.project` scopes everything downstream. Was this intentional for all consumers, or did a specific view need the filter?
+
+## Positive Notes
+<Praise, what's working well. Not filler; only when real.>
+
+- Consistent `#(doc)` coverage on the new `models/analytics/` source: 100% of public fields documented with business-language strings.
+- The `extend` chain restructuring in `models/marketing/attrib.malloy` is a real readability win; cross-cutting rename is clean.
+
+## Suggested Follow-ups (non-blocking)
+<Aggregated minor/nit findings. Point at the Detailed Findings section for specifics.>
+
+- 34 style nits aggregated, see S-series findings. Consider a follow-up PR or running `/malloy-review --apply` against those IDs.
+- Three backticked-passthrough dimensions (Y-series), recommend aliasing to business names.
+
+## Suggested Split (only if diff > 2000 LOC or >30 files)
+<Present only when the scope justifies it. Group files by coherent change themes.>
+
+This review covers 10,173 lines across 47 files. Only ~1,500 lines were deep-reviewed; the rest were sampled. A stacked PR sequence for next time:
+
+1. **Schema & staging**: `models/staging/*.malloy` + `publisher.json` bumps (12 files, ~1,800 LOC)
+2. **Shared joins and PK hygiene**: `models/shared/*.malloy` (4 files, ~400 LOC)
+3. **Finance domain**: `models/finance/*.malloy` (9 files, ~1,900 LOC)
+4. **Marketing domain**: `models/marketing/*.malloy` (11 files, ~2,300 LOC)
+5. **Governance & access annotations**: access-modifier pass across previously-shipped models (8 files, ~900 LOC)
+6. **Consumer views and dashboards**: `views/*.malloy` (3 files, ~2,800 LOC)
+
+## Machine-readable findings
+
+<!-- Stable schema; safe for downstream tools and a future --apply mode to parse. -->
+
+```json
+{
+  "schema_version": 1,
+  "scope": {
+    "paths": ["models/finance/", "models/shared/_joins.malloy"],
+    "packages": ["finance"],
+    "files_reviewed": 14,
+    "total_loc": 2912
+  },
+  "diagnostics_coverage": {
+    "available": 9,
+    "missing": 5,
+    "missing_files": ["models/finance/forecast.malloy", "..."]
+  },
+  "source_index": {
+    "customers": {"file": "models/shared/customers.malloy", "primary_key": "id", "pk_verified": false, "wave": 1},
+    "orders":    {"file": "models/orders.malloy",            "primary_key": "id", "pk_verified": true,  "wave": 1}
+  },
+  "findings": [
+    {
+      "id": "B1",
+      "severity": "critical",
+      "category": "correctness-join",
+      "blocking": "blocking",
+      "file": "models/finance/revenue.malloy",
+      "line_range": [142, 142],
+      "rule": "C-12 declared primary_key is not unique in the data",
+      "current": "join_one: customers on customer_id = customers.id; customers.id has duplicates (pk_verified=false)",
+      "expected": "customers.id is unique per row, or the customers source carries a where: that scopes to a uniquely-keyed subset",
+      "suggested_fix": "Aggregations across this join will silently return hash-collision-sized garbage. Pick a different / composite PK that IS unique, OR add a source-level where: that makes id unique within the filtered set, OR declare a #(filter) ... required annotation.",
+      "confidence": 95,
+      "evidence": "rubric-correctness C-12; pk_verified=false from SKILL.md step 3 execute_query check",
+      "source": "rule"
+    }
+  ],
+  "coverage_map": [
+    {"file": "models/finance/revenue.malloy", "loc": 412, "risk": "HIGH", "depth": "DEEP"}
+  ]
+}
+```
+```
+
+## Assembly rules
+
+1. **Sections are always emitted in this order.** Skip a section if empty, but don't reorder.
+2. **Top Issues caps at 25 inline entries.** If there are more blockers/criticals, list the first 25 and add a closing line: "...N additional blockers/criticals in Detailed Findings." This prevents API throttling on giant reviews.
+3. **Detailed Findings is always collapsed with `<details>` tags**, users click to expand only the files they care about.
+4. **JSON tail schema is stable (`schema_version: 1`).** Any future change to the shape bumps the version. The v2 `--apply` mode reads this.
+5. **Diagnostics-coverage note is always present** even if no diagnostics were available. Write "Diagnostics unavailable on this host; open the repo in an editor with the Malloy extension for compiler-grade findings."
+6. **"Suggested Split" section only appears** when the review scope is >2000 LOC or >30 files. Smaller reviews skip it entirely.
+7. **"Positive Notes" must be real**, don't fill it with generic praise. If nothing deserves praise, omit the section.
+8. **"Questions for the Author" is bounded to ≤5 bullets.** More than that means the summarizer pass didn't do its job; tighten that first, don't expand this.
+9. **File paths are always repo-relative**, never absolute paths, never `~/`-prefixed.
+
+## What the file does NOT contain
+
+- No per-agent breakouts ("structural reviewer said X, docs reviewer said Y"). The reader doesn't care which agent found something.
+- No rubric rule text in full, rubric references are by ID only (e.g., "rubric-correctness C-12"). The file cites where to look, it doesn't duplicate the rubric.
+- No debug traces, no token counts, no model names.
+- No raw diff. The reader has git for that.

package/skills/malloy-review/reference/rubric-correctness.md

@@ -0,0 +1,161 @@
+# Rubric: Correctness (Semantic Hazards Only)
+
+**Dimension:** `correctness-join | correctness-aggregation | correctness-type | correctness-filter`
+**Rules:** 9 (focused on silently-wrong behavior, not parse errors)
+
+This rubric only contains rules that the Malloy compiler does NOT catch. Parse errors, missing colons, `as` vs `is`, missing `->`, bare `join:`, `||` concat, unbacked reserved words, redefined query-source columns are all caught by the IDE diagnostic pre-pass (when available, via `mcp__ide__getDiagnostics`) and surface as `source: "diagnostic"` findings, the reviewer must not re-derive them.
+
+What this rubric covers is the dangerous middle ground: code that **compiles cleanly but is wrong**, silent cardinality bugs, division-by-zero, string aggregates, raw SQL bypassing Malloy's guarantees, declared primary keys that aren't actually unique in the data.
+
+**Rules we dropped after compiler-source / live-compile validation:**
+
+- **C-07 (missing `primary_key:` on a `join_one:` target).** Reading the Malloy compiler source (`packages/malloy/src/model/field_instance.ts:644-670`, `query_query.ts:946-951`) shows the compiler auto-synthesizes a UUID-based `__distinct_key` when the target lacks a declared PK, so symmetric aggregation is correct either way. The `with` shortcut (which DOES require a declared PK) is enforced by the compiler with a clear error and surfaces as a diagnostic. The remaining concern, "declared PK is a lie", is what C-12 below catches. The hygiene preference (declare a PK when one exists) lives in `rubric-structure.md` § S-02 as a `minor` recommendation; the style preference for using `with` consistently across the project lives in `rubric-style.md` § Y-03.
+- **C-08 (use method syntax for joined-field aggregation, e.g. `sum(items.cost)` → `items.cost.sum()`).** Confirmed against Malloy 0.0.370: `sum(joined.field)`, `avg(joined.field)`, `min(joined.field)`, and `max(joined.field)` are all **compile errors** with the message `Join path is required for this calculation; use 'items.cost.sum()'` (the diagnostic literally suggests the fix). The IDE diagnostic pre-pass surfaces this with a clearer message than the rubric ever could. The `count(joined.field)` carve-out, that it remains the canonical Malloy distinct-count idiom and should not be "fixed" to method syntax, is documented in `skill:malloy-gotchas-queries` § Aggregating Joined Fields, Method Syntax, which is where someone would land after seeing the compiler nudge.
+- **C-11 (`?` alternation joined by `and` rather than comma).** Validated against Malloy 0.0.370 across five arrangements. The compiler is never silently wrong here: `is_us = true and party ? 'D' | 'R'` (alternation second) compiles to the SQL the author intended (`WHERE is_us=true AND party IN ('D','R')`); `party ? 'D' | 'R' and is_us = true` (alternation first) and any pair of `?` alternations joined by `and` produce a clean compile error (`'logical operator' Can't use type string`). Either path is reviewer-safe, so the rubric doesn't need to flag it. Comma is still the canonical form because it's unambiguous in every position; that guidance lives in `skill:malloy-gotchas-queries` § `?` Alternation, Use Commas to Combine Filters.
+
+For every rule, the linked instruction-skill section is the canonical source for rationale and WRONG/RIGHT examples, read it once, don't paraphrase here.
+
+---
+
+## C-01: NULL checks: prefer `is not null` over `!= null`
+
+- **Severity:** major (non-blocking) · **Category:** correctness-filter · machine-checkable
+- **Detection:** regex `!=\s*null` or `=\s*null` in a `where:` clause or boolean-dimension expression. (Malloy uses `=` for equality, not `==`.)
+- **Fix:** `X is not null` or `X is null`
+- **Why non-blocking, Malloy itself recommends the form we're flagging.** The Malloy compiler emits a *warning* suggesting `!= null` over `is not null` ([`malloydata/malloy#1880`](https://github.com/malloydata/malloy/pull/1880)). Both forms compile. The reason this rubric still prefers `is not null` is that for the canonical boolean-dimension pattern `dimension: is_X is column != null`, Malloy evaluates `null != null` as `true` (bug [`malloydata/malloy#1968`](https://github.com/malloydata/malloy/issues/1968); fix proposal [`#2067`](https://github.com/malloydata/malloy/pull/2067) closed unmerged in Jan 2025), so the dimension marks null rows as `true` when the author intended `false`. Until that's resolved, `is not null` is the safer form for column-vs-null checks, even though the IDE will soft-warn the other way. Reviewers should weight this contradiction when assigning per-finding confidence.
+- **See:** `skill:malloy-gotchas-modeling` § NULL Checks, `is not null`, NOT `!= null`
+
+---
+
+## C-02: Date/time return-type confusion (`.month` vs `month()`)
+
+- **Severity:** major (non-blocking) · **Category:** correctness-type · LLM-judgment
+- **What this catches.** Malloy has two forms for date parts. Both compile cleanly, but they return different types:
+
+  | Syntax | Returns | Use for |
+  |---|---|---|
+  | `ts.year` / `ts.month` / `ts.quarter` / `ts.day` / `ts.week` | **Timestamp** truncated to that boundary (e.g. `@2024-03-01`) | Time-series chart axes, ordered grouping, range filters |
+  | `year(ts)` / `month(ts)` / `quarter(ts)` / `day(ts)` / `hour(ts)` | **Integer** (e.g. `2024`, `3`) | Cross-year buckets ("all Januaries together"), `pick when` integer comparisons, integer arithmetic |
+
+  The wrong choice is silent, there's no compile error. Concrete hazards:
+  - Chart view (`# bar_chart` / `# line_chart`) using `group_by: m is month(ts)` renders integers as `1, 10, 11, 12, 2, 3, …` (lexicographic order) instead of chronological months.
+  - `where: created_at.year > 2020` compares a timestamp (`@2020-01-01`) to integer `2020` and doesn't filter what the author intended.
+  - Cross-year "January totals" using `ts.month` produces 12 buckets *per year* (e.g. 60 buckets across 5 years) instead of 12 buckets total. The chart looks chronologically normal so the bug is easy to miss.
+- **Detection (context-dependent, LLM-judgment):**
+  - Chart view on a time axis using `<fn>(ts)` (integer form) → usually wants `ts.<part>` (timestamp form).
+  - `where:` / `pick when` / numeric comparison against an integer literal using `ts.<part>` (timestamp form) → usually wants `<fn>(ts)` (integer form).
+  - Aggregation labelled "monthly" / "by month" grouping on `ts.month` across multiple years → the actual bucket key is *month-and-year*, not *month-of-year*; the author probably meant `month(ts)`.
+- **Fix.** Pick the form the caller's context expects, and rename the dimension so the type is unambiguous in downstream code:
+  - Timestamp form → `<part>_at` / `<part>_truncated_at` (e.g. `month_truncated_at is created_at.month`).
+  - Integer form → `<part>_number` / bare `<part>` (e.g. `month_number is month(created_at)`).
+- **Not a finding (the compiler already catches these).** Using `.day_of_week`, `.hour`, `.minute`, `.second`, or `.week` on a timestamp errors at compile time, those date parts are *functions only*, not properties. The IDE diagnostic pre-pass surfaces them; don't re-emit as C-02.
+- **See:** `skill:malloy-gotchas-modeling` § Date Functions vs Properties · `skill:malloy-gotchas-queries` § Time Truncation vs Extraction
+
+---
+
+## C-03: Safe division with `nullif`
+
+- **Severity:** major (blocking) · **Category:** correctness-filter · machine-checkable
+- **Detection:** regex for `/` in measure/dimension expressions where the right-hand side is not a `nullif(...)` call
+- **Fix:** `<numerator> / nullif(<denominator>, 0)`
+- **See:** `skill:malloy-gotchas-modeling` § Safe Division, Always `nullif`
+
+---
+
+## C-04: Cast strings for aggregates
+
+- **Severity:** major (blocking) · **Category:** correctness-type · LLM-judgment
+- **Detection:** when an aggregate (`avg`, `sum`, etc.) wraps a column whose type is `STRING`, flag. To learn a column's type, ground yourself with `get_context` (it returns the sources and their fields), or sample the data with `execute_query` (`run: <source> -> { select: * limit: 1 }`).
+- **Fix:** `avg(score::number)` / `sum(amount::number)`
+- **See:** `skill:malloy-gotchas-modeling` § String Columns Need Casts for Aggregates
+
+---
+
+## C-05: Boolean comparisons use bare `true`/`false`
+
+- **Severity:** major (blocking) · **Category:** correctness-type · machine-checkable
+- **Detection:** regex for `=\s*['"]true['"]` or `=\s*['"]false['"]`
+- **Fix:** remove the quotes
+- **See:** `skill:malloy-gotchas-modeling` § Boolean Columns, No Quotes
+
+---
+
+## C-06: Don't combine `rename:` with `include {}` access-modifier blocks
+
+- **Severity:** major (blocking) · **Category:** correctness-syntax · machine-checkable (conditional)
+- **Detection:** find every `rename:` occurrence; flag ONLY when the same `source:` block also contains an `include {…}` clause. A `rename:` in a source without `include {}` is fine and must not be flagged.
+- **Why this is wrong:** `include {}` and `rename:` don't compose. `rename:` runs first at parse time, so by the time `include` tries to attach an access modifier the original column name is gone, Malloy errors `Can't find field 'X' to set access modifier`.
+- **Fix template, `include {}` is the curated default; only drop it when `rename:` is unavoidable:**
+  - **Preferred, preserve `include {}` (the curated default).** Eliminate the `rename:` so `include {}` can stay. Most often this means renaming the colliding *measure* (e.g., `measure: revenue` → `measure: total_revenue`) or splitting the source into a base + computed source. `include {}` is the canonical curated mode for documented base sources, it's the only way to attach `#(doc)` tags to raw columns and the recommended way to hide empty/garbage/duplicate columns via `internal:`. See `malloy-model/reference/access-modifiers.md`. Keep it whenever you can.
+  - **Fallback, drop `include {}` when the rename is unavoidable.** Some renames can't be eliminated without a downstream-breaking change: most commonly `sql()` → `table()` migrations where the original SQL alias matches a measure name that's already in heavy use across notebooks/dashboards. In that case, drop `include {}` and curate the source with `extend { except: a, b, c }` + `rename: raw_X is X` instead. You forfeit `#(doc)` on raw columns and the `public/internal/private` tiers, but keep column gating and the rename.
+- **Compile-error notes (validated):**
+  - `include { ... } extend { rename: A is B }` errors with `Can't find field 'B' to set access modifier` because `rename:` runs first and leaves no `B` for `include` to set a modifier on.
+  - `include { internal: X } extend { measure: X is ... }` errors with `Cannot redefine 'X'` because internal columns and measures share a namespace, Malloy disallows shadowing even for internal-tagged columns. The collision is what usually drives someone to add `rename:` in the first place.
+- **See:** `skill:malloy-gotchas-modeling` § Field Management, `extend {}` vs `include {}` Don't Compose · `malloy-model/reference/access-modifiers.md` (for the `include {}` capability tradeoffs)
+
+---
+
+## C-09: `count()` vs `count(field)`
+
+- **Severity:** major · **Category:** correctness-aggregation · LLM-judgment
+- **Detection:** when a measure name suggests counting a specific entity (`unique_customers`, `distinct_products`) but uses `count()` on a source whose grain is something else, flag
+- **Fix:** `count()` for rows; `count(x)` for distinct values of x. Make the measure name match the grain.
+- **See:** `skill:malloy-gotchas-modeling` (count semantics referenced throughout; weak counterpart, relies on reviewer judgment about measure-name-vs-grain mismatch)
+
+---
+
+## C-10: Use Malloy native patterns when available
+
+- **Severity:** major (non-blocking) · **Category:** correctness-syntax · LLM-judgment
+- **Detection:** find every `conn.sql(` occurrence, then **analyze the embedded SQL**:
+  1. Read the SQL string.
+  2. **MANDATORY pre-check, schema verification.** Use `execute_query` to run `run: <table_path> -> { select: * limit: 1 }` against the underlying table referenced in the SQL. Compare the table's column list to the SQL's `SELECT` list. **Any column in the table that's NOT in the SELECT was being intentionally hidden by the SQL.** If so, the migration must preserve gating via `extend { except: ... }`, NOT just swap `sql()` → `table()`. Especially watch for columns named `month_*`, `weekly_*`, `daily_*`, `total_*`, `cum_*`, `running_*`, or anything matching `(month|day|week|hour)_<measure>`, these are typically pre-aggregated per-period rollups that would silently double-count if exposed and summed.
+  3. Identify constructs used: `SELECT`, `GROUP BY`, `JOIN`, `CASE WHEN`, window functions (`LAG`, `LEAD`, `ROW_NUMBER`, `RANK`, `OVER`), CTEs, lateral joins, UNNEST, PIVOT, latest-snapshot subqueries, DB-specific functions, column aliases (`X AS Y`).
+  4. **MANDATORY: call `search_malloy_docs` for each non-trivial construct**, window functions, CTE chains, UNNEST/array access, PIVOT/conditional aggregation, latest-snapshot lookups. "When unsure" historically read as "never", agents skipped this step and asserted `conn.sql()` was justified when in fact Malloy expressed the pattern fine. The skip is not allowed. Record the search queries you ran inline in the finding's `suggested_fix` so the user can audit them.
+  5. **If every construct has a Malloy equivalent** → flag, with a sketched rewrite that includes the preserved gating clause.
+  6. **If any construct genuinely requires raw SQL** → don't flag, but the genuine-requirement list is narrow (DML/DDL, certain `MERGE` patterns). Do not accept "Malloy can't express this cleanly" without citing a specific `search_malloy_docs` query that returned no equivalent.
+- **Common mappings the agent should know:**
+  - `SELECT col, AGG(...) FROM x GROUP BY col` → `x -> { group_by: col; aggregate: ... is ... }`
+  - `SELECT explicit_cols FROM x` (column gating) → `x extend { except: <columns_not_in_SELECT> }` or `accept: <columns_in_SELECT>`
+  - `SELECT col_x AS col_y FROM x` → `extend { rename: col_y is col_x }`
+  - `SELECT CAST(ROUND(a * b) AS INT64) AS total FROM x` → `extend { dimension: total is round(a * b)::number }`
+  - `WHERE created_at > '2024-01-01'` → `extend { where: created_at > @2024-01-01 }`
+  - `LAG/LEAD/ROW_NUMBER/RANK ... OVER (...)` → `calculate: ... is lag(...)`, `rank()`, etc.
+  - **`SUM(x) OVER (PARTITION BY ... ORDER BY ... ROWS UNBOUNDED PRECEDING)`** → `calculate: c is sum_cumulative(x) { partition_by: ...; order_by: ... asc }`
+  - **`SUM(x) OVER (... ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING)`** (cumulative-excluding-current) → `sum_cumulative(x) - x` with the same `partition_by`/`order_by`
+  - **Multi-CTE pipelines** → stacked query-based sources: `source: a is t -> {...}`; `source: b is a -> {...}`
+  - **UNNEST / array access** → `array_column.each.field` ([data types docs](https://docs.malloydata.dev/documentation/language/datatypes#array-access))
+  - **PIVOT / `SUM(CASE WHEN cat = 'a' THEN x END)`** → filtered aggregates: `aggregate: a is x.sum() { where: cat = 'a' }`
+  - **`WHERE date = (SELECT max(date) FROM …)`** (latest snapshot) → `join_cross` to a one-row aggregate source, then filter on the joined `max_date` field
+  - **Multi-key joins (`ON a.x = b.x AND a.y = b.y`)** → `join_one: b on x = b.x and y = b.y`
+  - `CASE WHEN ... THEN ... ELSE ... END` → `pick ... when ... else ...`
+  - `GREATEST(a, b)` / `LEAST(a, b)` → native: `greatest(a, b)` / `least(a, b)` (work as Malloy dimensions, no `conn.sql()` needed)
+  - `COALESCE(a, b)` → `a ?? b`
+  - `CAST(x AS y)` → `x::y`
+  - Dialect-specific scalar functions Malloy doesn't model → `function_name!return_type(args)` (raw-SQL function escape; does NOT require `conn.sql()`)
+- **The `rename:` chain pattern.** When the original SQL re-used column names via a swap (e.g., `SELECT cash_month AS payment_date, payment_date AS payment_day`), Malloy supports the same swap as two ordered `rename:` clauses: `rename: payment_day is payment_date` (frees the name), then `rename: payment_date is cash_month` (re-uses it). Malloy evaluates renames in source-block order. (`rename:` works inside `extend {}` alongside `except:` / `accept:` but **not** alongside `include {}`, see C-06.)
+- **Fix:** propose the equivalent Malloy when expressible, **preserving the column gating** discovered in the pre-check step. When not expressible, the rule doesn't fire, leave `conn.sql()` alone.
+- **Worked cautionary example:** A reviewer once tier-classified a 6-CTE 148-line `sql()` block (forecast pipeline with multi-key joins, latest-snapshot, custom-frame window function, conditional pivot, transfer-math `GREATEST/LEAST` chains) as "justified, Malloy can't express the window function with `ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING` cleanly." They never called `search_malloy_docs`. After actually searching, the equivalent is `sum_cumulative(x) - x { partition_by: ... }`, eight lines. The port came out 160 lines (12 more than the SQL), byte-identical across 2,160 cells of test data. The "Malloy can't do this" intuition was wrong, and the cost was duplicated review work plus several years of avoidable `conn.sql()` maintenance burden. **If you (the reviewer) catch yourself writing "this is awkward in Malloy" without having searched, stop and search.**
+- **See:** `skill:malloy-gotchas-modeling` § Never Use `conn.sql()` When Malloy Has a Native Pattern (canonical equivalence table) · `skill:malloy-gotchas-modeling` § Field Management, `extend {}` vs `include {}` Don't Compose
+
+---
+
+## C-12: Declared `primary_key:` must actually be unique in the data
+
+- **Severity:** critical (blocking) · **Category:** correctness-join · machine-checkable (data-driven)
+- **Detection:** SKILL.md step 3 runs `execute_query` for each source with a declared `primary_key:` and merges the result into `source_index.<src>.pk_verified` as `true | false | "skipped" | "error"`. **Emit C-12 only when `pk_verified == false`**, the source's declared PK has duplicates in the data. When `pk_verified` is `"skipped"` or `"error"`, do not emit; note the diagnostic-coverage gap in the output's Scope section instead.
+- **Why this matters:** Malloy's symmetric-aggregation SQL relies on `HASH(pk) * 1e15` being unique per row. If the PK is a lie, the `DISTINCT` step collapses what shouldn't, and aggregations across `join_one:` to this source return hash-collision-sized garbage (~10²¹). The filter that "fixes" the symptom is doing so accidentally, by happening to produce a uniquely-keyed subset.
+- **Fix template:** three paths:
+  1. Pick a different (or composite) PK that *is* unique. For composite keys in Malloy, derive a single dimension that concatenates the key columns and use that as `primary_key:`.
+  2. Add a source-level `where:` that makes the existing PK unique within the filtered set (acceptable when the filter is the source's intended scope).
+  3. Declare a `#(filter) … required` annotation per the publisher filter mechanism so consumers must supply the discriminating filter (your documentation guidance on the `#(filter)` Tag, Declare Parameterizable Filters).
+- **See:** `malloy-model/reference/bridge-tables.md` § Cardinality Verification · your documentation guidance (#(filter) Tag, Declare Parameterizable Filters) (for the `required` filter remediation path)
+
+---
+
+## Detection guidance for the correctness reviewer
+
+1. **Consume diagnostics first**, SKILL.md step 2 already mapped IDE diagnostics to findings with `source: "diagnostic"`. Parse errors, syntax errors, missing colons, missing arrows, unbacked reserved words, redefined columns, all the compiler's job. Don't re-emit; don't add rubric rules for compile-caught problems.
+2. **Focus on silently-wrong behavior.** Every rule here is a case where the code compiles but is semantically incorrect.
+3. **Work from the rubric, not from intuition**, only emit findings that map to a rule ID here. If you see a semantic problem that doesn't match any rule, emit it as `rule: "judgment"` and explain it.
+4. **Emit nothing if the rule doesn't fire.** The output should feel curated, not exhaustive.

package/skills/malloy-review/reference/rubric-documentation.md

@@ -0,0 +1,69 @@
+# Rubric: Documentation
+
+**Dimension:** `docs`
+**Rules:** 5
+
+A field is not "complete" until it has its definition, a `#(doc)` string, and any rendering tags it needs. This rubric enforces that standard against any `.malloy` file that defines sources, dimensions, measures, or views.
+
+For every rule, the linked instruction-skill section is the canonical source for rationale, examples, and the writing-style guidance that drives the rule. The rubric carries detection and fix metadata only.
+
+---
+
+## D-01: Public-surface fields must have `#(doc)`
+
+- **Severity:** major (blocking) on public · minor (non-blocking) on internal · **Category:** docs · machine-checkable
+- **What counts as a public-surface field**, every field a downstream consumer can pick:
+  - **Raw columns listed under `public:` in an `include {}` block** (requires `##! experimental.access_modifiers`). ID columns count too, the team standard is "every public column has a `#(doc)`." See your documentation guidance (Annotating Columns in Include (Experimental)) for the canonical shape.
+  - **Every `dimension:` and `measure:` declaration in `extend {}`**, these are public unless the source is fully internal-tagged.
+  - Raw columns under `internal:` / `private:` are exempt (use D-01 internal severity if you want to flag missing docs as a soft nudge).
+- **Detection:** for each public-surface field in scope, check whether the immediately preceding tag block contains a `#(doc)` tag. Missing → flag.
+  - When access modifiers are in use (`##! experimental.access_modifiers`), missing `#(doc)` on any public-surface field is `major (blocking)`, the curated `include {}` is the contract, and an undocumented public column short-circuits the documentation discipline (see G-01).
+  - Without access modifiers, default to `major (non-blocking)` for `dimension:` / `measure:` declarations because we can't tell which raw columns are public.
+- **Fix:** add a one-line `#(doc)` above the field describing business meaning and units. For raw columns under `public:`, this is the only place to attach business documentation, there's no `dimension:` declaration to hang it on.
+- **See:** your documentation guidance (#(doc) Tag) · your documentation guidance (Annotating Columns in Include (Experimental))
+
+---
+
+## D-02: `#(doc)` strings avoid Malloy jargon
+
+- **Severity:** minor (non-blocking) · **Category:** docs · LLM-judgment
+- **Detection:** keyword heuristic first pass, flag `#(doc)` strings containing `aggregation`, `filterable`, `groupable`, `dimension`, `measure`, `aggregate`, `field`. Confirm with LLM judgment on the actual string.
+- **Fix:** rewrite in business language, what is it, what are its units, what values does it take
+- **See:** your documentation guidance (Writing Doc Strings for Retrieval)
+
+---
+
+## D-04: One tag per line
+
+- **Severity:** minor (if-minor) · **Category:** docs · machine-checkable
+- **Detection:** regex, a line containing two or more `#` tag openers outside quoted strings
+- **Fix:** split onto separate lines
+- **See:** `skill:malloy-gotchas-rendering` § One Tag Per Line
+
+---
+
+## D-06: Source-level documentation describes **when to use** the source
+
+- **Severity:** major (blocking) on joined sources · minor (non-blocking) on base sources · **Category:** docs · LLM-judgment
+- **Detection:** LLM judgment on whether the source-level `#(doc)` is substantive. A string that just echoes the table name (e.g., `#(doc) Customers`) is flagged.
+- **Fix:** rewrite to describe grain (base) or analytical use (joined)
+- **See:** your documentation guidance (Source-Level Documentation)
+
+---
+
+## D-07: Filtered measures document the filter intent
+
+- **Severity:** major (blocking) · **Category:** docs · LLM-judgment
+- **Detection:** for every `measure:` containing a `{ where: }` filter block, the `#(doc)` string must mention the filter criterion (heuristic: contains at least one word from the filter expression, or mentions `filter`/`only`/`excludes`/`includes`). LLM confirms.
+- **Fix:** extend the doc to explain what the filter includes/excludes
+- **See:** your documentation guidance (Writing Doc Strings for Retrieval) (filtered-measure intent is implicit; weak counterpart)
+
+---
+
+## A note on coverage metrics
+
+The docs reviewer also emits an aggregate observation in the review's Cross-Cutting Themes when coverage drops:
+
+- **Doc coverage** = (fields with `#(doc)`) / (all public fields) × 100
+
+If it drops notably relative to the rest of the reviewed scope (e.g., one file at 40% when the rest are 90%+), surface it as a theme, not just per-field findings.

package/skills/malloy-review/reference/rubric-governance.md

@@ -0,0 +1,37 @@
+# Rubric: Governance & Access
+
+**Dimension:** `governance`
+**Rules:** 2
+
+Governance findings cover access modifiers when the experimental feature is in use. Source-level `where:` filters and `private:` choices are **deliberate modeling decisions**, the reviewer trusts the modeler on those, not the rubric. If something looks unusual, surface it as a "Question for the Author," not a finding.
+
+For every rule, the linked instruction-skill section is the canonical source for rationale and examples.
+
+---
+
+## G-01: Enumerate `public:` columns explicitly with `#(doc)`
+
+- **Severity:** minor (non-blocking) · **Category:** governance · machine-checkable
+- **Detection:** regex for `public:\s*\*` inside an `include {}` block
+- **Fix:** enumerate public columns explicitly, each with a `#(doc)` tag and any necessary rendering tags. If you really do want every column public, list each one, the per-column `#(doc)` is the point.
+- **See:** your documentation guidance (Annotating Columns in Include (Experimental)) · `malloy-model/reference/access-modifiers.md`
+
+The reason `public: *` is discouraged is **documentation discipline**, not access semantics. With `public: *`, none of the wildcard-included columns get individual `#(doc)` tags, which short-circuits AI discoverability. The team standard is "every public column has a `#(doc)` tag." If a modeler genuinely wants everything public on a small curated source, that's their call, the rule raises awareness (`minor`/`non-blocking`), it doesn't block.
+
+---
+
+## G-02: Access modifiers are explicit when `##! experimental.access_modifiers` is on
+
+- **Severity:** major (blocking) · **Category:** governance · LLM-judgment (cross-file)
+- **Detection:** if a file has `##! experimental.access_modifiers`, cross-reference columns in `include {}` against the source's full column set. Ground yourself with `get_context` to learn which columns the underlying table exposes (or sample the data with `execute_query`: `run: <source> -> { select: * limit: 1 }`). Any column missing from the block is a finding.
+- **Fix:** add every column to `include {}` as `public:` (with `#(doc)`) or `internal:`; confirm `private:` with the user before marking
+- **See:** your documentation guidance (Annotating Columns in Include (Experimental)) · `malloy-model/reference/access-modifiers.md`
+
+---
+
+## What this rubric does NOT flag
+
+- **Source-level `where:` clauses.** Encapsulating filters at the source level is a core feature of semantic modeling, it lets callers query the source without knowing the filter details. The rubric does not flag this as a hazard. If a reviewer thinks a specific source-level `where:` looks unusual (e.g., a new scoping filter introduced in a PR), surface that as a "Question for the Author" in the output, not as a rubric finding.
+- **`private:` choices on PII-adjacent columns.** Marking email/phone/address as `private:` is the modeler's deliberate choice. The reviewer doesn't second-guess it. Same fallback applies, if it looks unusual, ask in the questions section.
+
+These are *modeling features*, not *governance violations*. The rubric should catch real mistakes, not impose style preferences on deliberate access-modifier choices.

package/skills/malloy-review/reference/rubric-queries.md

@@ -0,0 +1,78 @@
+# Rubric: Queries & Views
+
+**Dimension:** `queries`
+**Rules:** 4 (focused on shape and judgment, not parse errors)
+
+Applies to in-scope `.malloy` files containing `view:` or `run:` definitions. If a file has no views or runnable queries, skip this rubric for that file.
+
+Compile-caught query mistakes, trailing commas between clauses, `having:` at source level, unaliased dotted paths in `order_by:`, window functions outside `calculate:`, `nest:` group-by fields that don't exist on the parent source, `where:` on a name that resolves to an aggregate, are all surfaced by the IDE diagnostic pre-pass with clear messages. The reviewer must not re-derive them.
+
+What this rubric covers is the **shape and intent** of views: chart-rendering choices, reusability, time-axis judgment, and exploratory ergonomics. These survive compilation but make queries less useful or harder to maintain.
+
+For every rule, the linked instruction-skill section is the canonical source for rationale and WRONG/RIGHT examples.
+
+---
+
+## Q-01: Charts render one aggregate only
+
+- **Severity:** major (non-blocking) · **Category:** queries · machine-checkable
+- **Detection:** within a view preceded by a chart-rendering tag (`# bar_chart`, `# line_chart`, `# scatter_chart`, `# shape_map`, `# segment_map`), count `aggregate:` lines AND `group_by:` lines.
+  - **Bug shape:** chart tag + ≥2 aggregates + ≤1 group_by + no `y=[...]` spec → flag. Only the first aggregate renders; the rest are silently dropped.
+  - **Already correct (no flag):** chart tag + 1 aggregate + ≥2 group_bys → the second group_by drives the chart series (e.g. `time × category`).
+  - **Already correct (no flag):** chart tag + `y=['col1', 'col2']` on the tag → multi-series rendering. Verify the `y=[...]` syntax per `rubric-rendering.md` § R-10 (must be flat properties + quoted strings).
+- **Fix template, three patterns based on the view's shape:**
+  1. **Multi-series via `y=[...]`**, when 2 aggregates share a Y-axis scale (both counts, or both currencies). Example: `# line_chart { y=['new_customers', 'returning_customers'] }` over `group_by: order_year_month`. Note the QUOTED STRINGS in the array; bare identifiers silently render only the first measure.
+  2. **Strip the chart tag**, when 3+ aggregates, or when 2 aggregates have different units (currency + count + rate). Leave the view as a data table; consumers chart whichever metric they care about. This is the established pattern in mart-derived files where one view exposes ~10 KPIs.
+  3. **Keep single aggregate + 2 group_bys**, when there's a natural category dimension to drive the series. Drop the extra aggregates from the chart-tagged view; if needed, create separate views per metric.
+- **See:** `skill:malloy-gotchas-queries` § Charts, ONE Aggregate Per View · `skill:malloy-charts` § Multi-Series Charts · `rubric-rendering.md` § R-10 (multi-series syntax gotchas)
+
+---
+
+## Q-02: Define measures in the source, not inline in views (DRY)
+
+- **Severity:** minor (non-blocking) · **Category:** queries · LLM-judgment, but **promote to `major (blocking)` when the inline measure is `avg(<per_row_rate_dimension>)`** (see "high-priority sub-pattern" below).
+- **Detection:** AST: flag `aggregate: <name> is <expression>` inside a view where the expression is non-trivial (more than a column reference). LLM judgment on whether the expression is reusable.
+- **Fix:** move the measure definition into the source; reference by name in the view.
+- **See:** `skill:malloy-gotchas-queries` § DRY, Define in Source, Reference in View
+
+**High-priority sub-pattern, inline `avg(per_row_rate)` IS the avg-of-rate anti-pattern.**
+
+When a source defines a row-level ratio as a dimension (often with a docstring like "Row-level ratio for averaging in views" or "per-row CM3 ratio") AND views use `aggregate: avg_X is avg(rate_dimension)`, you have **two converging bugs in one place**:
+
+1. The inline measure is a Q-02 DRY violation.
+2. `avg(per_row_rate)` is the avg-of-rate anti-pattern: it gives every row equal weight regardless of underlying volume, dramatically overstating or distorting performance metrics.
+
+**Detection heuristic:** when you see `aggregate: avg_X is avg(Y)` inside a view body, check if `Y` is defined as a `dimension:` on the source AND whether that dimension is itself a ratio (`A / nullif(B, 0)`). If so, this is the high-priority sub-pattern.
+
+**Fix template:**
+
+1. Check whether the source ALREADY has a volume-weighted measure that does the math correctly: `measure: cm3_percentage is attributed_cm3 / nullif(attributed_revenue, 0)`. If yes, replace each inline `avg_X is avg(rate)` with `avg_X is cm3_percentage` (or whatever the correct source measure is). This preserves the public column name `avg_X` for backward compatibility while fixing the math.
+2. If no source-level measure exists, define one: `measure: X_weighted is sum_of_numerator / nullif(sum_of_denominator, 0)`.
+3. Mark the row-level ratio dimensions `# (doc) DEPRECATED, per-row ratio, do not average. Use X_weighted instead.` so future readers don't re-introduce the pattern.
+
+**Magnitude check:** switching `avg_roas` from `avg(roas_value)` to volume-weighted `roas` (`attributed_revenue / attributed_marketing_spend`) corrected a **4.5× overstatement** of marketing ROI (0.289 reported vs 0.063 actual) in a real model. Inline avg-of-rate is rarely off by less than 10%; the rule is worth promoting to `blocking` once you see the pattern.
+
+---
+
+## Q-03: Time truncation vs extraction, pick the right one for the context
+
+- **Severity:** major (non-blocking) · **Category:** correctness-type · LLM-judgment
+- **Detection:** when `month()` / `year()` / `day_of_week()` is used in a `group_by:` whose view is a time-series chart, suggest the truncation form (`.month`, etc.). The reverse (using `.year` where integer extraction was wanted) is rare but possible.
+- **Fix:** swap the form; for year integers add `# number=id` to suppress comma formatting (R-06)
+- **See:** `skill:malloy-gotchas-queries` § Time Truncation vs Extraction
+
+---
+
+## Q-04: Cap `limit:` where it matters
+
+- **Severity:** nit (non-blocking) · **Category:** queries · machine-checkable
+- **Detection:** regex: a `run:` or top-level `query:` with an `order_by: ... desc` clause and no `limit:`. Only flag in exploratory contexts, scheduled jobs or full extracts may intentionally omit.
+- **Fix:** add a reasonable `limit:` (20/50/100); suggest the number, let the user tune
+- **See:** weak counterpart in instruction skills, exploratory ergonomics convention rather than a taught principle
+
+---
+
+## Detection guidance for the queries reviewer
+
+1. **Consume diagnostics first.** Trailing commas, `having:` at source level, unaliased dotted paths in `order_by:`, window functions outside `calculate:`, missing fields in `nest:` group-bys, `where:` on aggregate names, all parse/compile errors handled by the IDE pre-pass. Do not re-derive.
+2. **Focus on shape, not syntax.** Q-01 is about chart-rendering behavior; Q-02 is about reuse; Q-03 is about which time form fits the consuming view; Q-04 is about result-set ergonomics. None of these fail at compile time.