dataface 0.1.2__py3-none-any.whl

dataface/ai/skills/before-after-comparison/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: before-after-comparison
+kind: pattern
+description: >
+  Pattern for placing two metric series on the same axis to compare baseline
+  vs current, plan vs actual, or A vs B. Use when the question is "how does
+  current compare to baseline?" for the same set of categories or time periods.
+  Triggers on: 'compare', 'baseline vs current', 'plan vs actual', 'before
+  after', 'A/B', 'target vs actual', 'layered bars'. Both series share the same
+  x-axis encoding. Do NOT use for time-series trend (use time-series-trend).
+  Do NOT use for more than 3 series (chart becomes unreadable).
+metadata:
+  author: fivetran
+---
+
+# Before-After Comparison
+
+Two series rendered on the same bar or line chart, sharing the x-axis, so the
+viewer can compare baseline vs current or plan vs actual across categories or
+time periods. Use `y: [series_a, series_b]` for layered bars, or `color:` for
+grouped multi-series.
+
+## When to reach for this
+
+- "How does Q4 compare to Q3 for each region?"
+- "Are we above or below plan by category?"
+- The comparison dimension is the same set of x values for both series
+
+## When NOT to use this
+
+- Trend over time on a single metric → `time-series-trend`
+- More than 3 series → too cluttered; split into separate charts
+- Composition (parts of a whole) → stacked area in `faceted-small-multiples`
+
+## The pattern
+
+```yaml
+queries:
+  plan_vs_actual:
+    sql: |
+      SELECT category,
+             SUM(actual_revenue)  AS actual,
+             SUM(planned_revenue) AS plan
+      FROM budget
+      GROUP BY category
+      ORDER BY actual DESC
+
+charts:
+  comparison:
+    type: bar
+    query: plan_vs_actual
+    x: category
+    y: [actual, plan]        # two series, same x
+    title: Actual vs Plan by Category
+```
+
+For time-based comparisons, use two separate columns in one query and map with
+`color:` instead:
+
+```yaml
+queries:
+  by_month:
+    columns: [month, current, prior]
+    values: ...
+
+charts:
+  trend_compare:
+    type: line
+    query: by_month
+    x: month
+    y: [current, prior]
+    title: Current vs Prior Period
+```
+
+See `examples/before-after-comparison.yml` for the inline-data worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| Layered bars | `y: [a, b]` | Side-by-side bars per category |
+| Two line series | `y: [a, b]` on `type: line` | Time-based trend comparison |
+| Multiple categories | keep `x:` categorical | Natural for department/region comparisons |
+| Delta column | add a computed delta in SQL | Explicitly show the gap |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Series on different scales | Misleading visual; one series dwarfs the other | Use matching units or a secondary axis |
+| Too many series (`y: [a, b, c, d]`) | Legend and bars both unreadable | Cap at 2–3 series; combine the rest |
+| Different x-values per series | Chart gaps or misaligned bars | Ensure both series have a value for every x |
+| Swapped series order | Baseline visually dominates current | Put the primary/current series first in `y:` |
+
+## Worked example
+
+See `examples/before-after-comparison.yml` — four departments comparing
+current vs baseline spend. Inline data, no warehouse needed.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/before-after-comparison/examples/before-after-comparison.yml

@@ -0,0 +1,24 @@
+title: Q4 Budget vs Actual
+description: Before-after comparison pattern — two series (current and baseline) on the same bar chart
+
+queries:
+  budget_vs_actual:
+    description: Current quarter spend vs prior-quarter baseline by department
+    columns: [department, current, baseline]
+    values:
+      - [Engineering, 420000, 380000]
+      - [Marketing,   185000, 210000]
+      - [Sales,       340000, 295000]
+      - [Support,      95000, 105000]
+
+charts:
+  comparison_bar:
+    description: Current vs baseline spend — bars sit side by side per department
+    type: bar
+    query: budget_vs_actual
+    x: department
+    y: [current, baseline]
+    title: Q4 Actual vs Prior Quarter by Department
+
+rows:
+  - comparison_bar

dataface/ai/skills/dashboard-build/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: dashboard-build
+kind: workflow
+description: >
+  Core workflow for building dashboards and reports with Dataface. Use when
+  creating new dashboards, editing existing YAML, adding charts, writing
+  queries, iterating on layout, or when the user says 'build a dashboard',
+  'create a report', 'add a chart', 'write a query'. Covers the
+  build-test-iterate cycle, parameterized queries, caching, and incremental
+  development. Do NOT use for diagnosing errors after something breaks (use
+  dataface-troubleshooting). Do NOT use for design decisions about
+  chart types or layout patterns (use dashboard-design or
+  report-design).
+metadata:
+  author: fivetran
+---
+
+# Building Dataface Dashboards
+
+Build dashboards and reports **incrementally** — one chart at a time, validating at every step. Never one-shot an entire dashboard.
+
+## Companion Skills
+
+- **`{{ s_skill_design_dashboard }}`** — chart-type, layout, and color decisions
+- **`{{ s_skill_design_report }}`** — narrative reports (text + charts)
+- **`{{ s_skill_review }}`** — self-review checklist run at delivery
+- **`{{ s_skill_troubleshooting }}`** — when something breaks
+
+{{ s_docs_discovery }}
+
+## Metadata Requirement
+
+Fill `description` on every named object — agents downstream rely on it for context and search:
+
+- `queries.*.description` — what the query returns and why it exists
+- `charts.*.description` — what question the chart answers
+- `variables.*.description` — how the variable should be used
+- Layout objects (`rows`/`cols`/`grid.items`/`tabs.items`) — section intent when useful
+
+Keep each description short and factual (one sentence).
+
+## The Workflow
+
+### Step 1 — Explore the Data
+
+{{ s_explore_schema_first }}
+
+Use `{{ s_execute_query }}` to verify cardinality and sample values before writing any YAML:
+
+```sql
+SELECT status, COUNT(*) FROM orders GROUP BY status;
+```
+
+**Do not skip this step.** Writing SQL against assumed column names is the #1 source of errors.
+
+### Step 2 — Build One Chart
+
+Write a minimal YAML with a single query and chart:
+
+```yaml
+source: my_profile
+queries:
+  revenue:
+    sql: SELECT date, SUM(amount) AS total FROM orders GROUP BY date ORDER BY date
+charts:
+  revenue_trend:
+    query: revenue
+    type: line
+    x: date
+    y: total
+rows:
+  - revenue_trend
+```
+
+Then verify with two calls:
+
+1. `{{ s_execute_query }}` — confirm the data shape and columns
+2. `{{ s_render_dashboard }}` — compile + render to see the visual
+
+### Step 3 — Iterate on That Chart
+
+Adjust SQL, chart type, labels, colors. {{ s_render_to_verify }}
+
+### Step 4 — Add the Next Chart
+
+Repeat steps 2–3 for each additional chart. One at a time.
+
+### Step 5 — Compose the Layout
+
+Once all charts work individually, arrange them in `rows:` / `cols:`. The layout is the easy part — getting the queries right is the hard part.
+
+```yaml
+rows:
+  - cols: [kpi_revenue, kpi_users, kpi_orders]
+  - cols: [revenue_trend, 2]    # 2 = column span
+  - cols: [by_region, by_product]
+```
+
+### Step 6 — Save the Final YAML
+
+Write the YAML under `faces/` with your normal file-edit mechanism, then:
+
+{{ s_validate_example }}
+
+Fix any errors `{{ s_validate_dashboard }}` reports, then re-run until it passes.
+
+## Parameterized Queries — Use From the Start
+
+Use `{{ variable_name }}` syntax for any configurable values, even during exploration:
+
+```sql
+SELECT * FROM orders WHERE region = '{{ region }}' AND date >= '{{ start_date }}'
+```
+
+Pass concrete values via the `variables` parameter when testing. When the query moves into dashboard YAML it works identically — and results are already cached.
+
+**If you hardcode values during exploration and switch to variables later, the cache won't help because the SQL template changed.**
+
+## Validate Early and Often
+
+| Tool | When | What It Catches |
+|------|------|-----------------|
+| `{{ s_execute_query }}` | While drafting raw SQL | SQL errors, missing tables, wrong column names |
+| `{{ s_validate_dashboard }}` | After every YAML edit | YAML schema errors, unknown fields, broken chart/query/layout references |
+| `{{ s_query_face }}` | After saving YAML with named queries | Actual named-query columns and sample rows |
+| `{{ s_render_dashboard }}` | Before delivery | Query execution, render errors, layout issues, misleading visuals |
+
+These tools are fast. Use them after every change, not just at the end.
+
+## Self-Review Before Delivering
+
+Run the review skill as the final step before declaring the face done:
+
+- {{ s_review_pointer }}
+
+It orchestrates structural ({{ s_validate_dashboard }}) and visual (PNG + vision) passes and returns a ranked findings list. Fix each `blocker`, then re-run the review. Rendering and validation are cached — the loop is cheap.
+
+## Data Requirements Per Chart Type
+
+Each chart type expects data in a specific shape. Dataface validates this and errors fast — no silent magic.
+
+| Chart Type | Expected Data | Key Fields |
+|------------|---------------|------------|
+| `kpi`      | **Exactly 1 row** with a value column | `value` (column reference) |
+| `line`     | Multiple rows, temporal x + numeric y | `x`, `y` |
+| `bar`      | One row per category, numeric y       | `x`, `y` — categorical x auto-flips to horizontal; override with `style.orientation: vertical` only when needed |
+| `area`     | Multiple rows, temporal x + numeric y | `x`, `y` |
+| `scatter`  | Multiple rows, both x and y numeric   | `x`, `y` |
+| `pie`      | One row per segment (pre-aggregated)  | `theta` (numeric) + `color` (category) |
+| `heatmap`  | One row per cell (pre-aggregated)     | `x`, `y`, `color` |
+| `table`    | Any number of rows and columns        | Use `style.columns` for per-column formatting: `- column: amount` / `format: currency_whole` / `label: Amount` / `align: right` / `width: 120` |
+
+**Critical rules:**
+
+- **KPI charts require exactly 1 row.** Aggregate to a single row: `SELECT SUM(amount) AS total FROM orders`. Multiple KPIs need separate single-row queries (or one query with multiple columns).
+- **Pie and heatmap expect pre-aggregated data.** Use `GROUP BY` in the query. Dataface does NOT aggregate for you.
+
+## Formatting Numbers
+
+Dataface auto-detects number format from column name and DB type — omit `format:` when auto-detection would produce the correct result (e.g. a column named `conversion_rate` already renders as a percentage).
+
+When you do need an explicit format, use a named preset instead of a raw D3 string:
+
+| Preset | Example output |
+|--------|---------------|
+| `integer` | `1,234` |
+| `currency_whole` | `$1,234` |
+| `currency_compact` | `$1.2M` |
+| `percent` | `2.3%` — input is decimal fraction (0.023) |
+| `percent_number` | `2.3%` — input is whole-number percent (2.3) |
+| `percent_delta` | `+2.3%` — input is decimal fraction |
+| `percent_number_delta` | `+2.3%` — input is whole-number (2.3) |
+
+Full preset list and auto-detection rules: see `dashboard-structural-review`.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Building the entire dashboard in one pass | Build one chart at a time |
+| Writing SQL without checking column names | Use `{{ s_schema }}`, `{{ s_schema_search }}`, or `{{ s_execute_query }}` first |
+| Hardcoding values during exploration | Use `{{ variables }}` from the start so the query cache survives |
+| Skipping validation between changes | `{{ s_validate_dashboard }}` after every YAML edit |
+| Too many charts (>8) | Split into multiple dashboards |
+| Using chart-type names as keys in layout | `table:` or `bar:` as keys cause parse errors — use descriptive names like `revenue_table` |
+| Referencing query names in layout | Layout references charts, not queries — create a chart that wraps the query |
+| KPI query returns multiple rows | Use `SUM()`/`COUNT()`/`AVG()` to aggregate to 1 row |
+| Pie with raw unaggregated data | `GROUP BY` in query to aggregate before charting |
+| Putting `height:` or `aspect_ratio:` under `style:` | Move them to chart root: `charts.my_chart.height: 400` — `style:` is paint only |
+| Writing raw D3 format strings (`"$,.2s"`, `".1%"`) | Use a named preset (`currency_compact`, `percent`) — clearer and theme-consistent |
+| Setting `format:` when auto-detection already matches | Omit `format:` for columns like `*_pct`, `*_rate`, `*revenue*` — auto handles them |
+| Nesting `columns`/`values` under `sql:` for inline data | `sql:` is a string — inline data lives directly under the query name: `queries.my_data.columns: [...]` and `queries.my_data.values: [[...]]` |
+| Filtering a multiselect with `{{ plans \| map('tojson') \| join(', ') }}` | `tojson` produces double-quoted strings that SQL treats as column refs — silent empty result, `dft render` exits 0. Use `{{ filter('plan', plans) }}` instead. |
+
+## Rationalizations to Resist
+
+| Excuse | Reality |
+|--------|---------|
+| "User asked for the whole dashboard at once" | Build incrementally anyway. Iterate to the result, don't one-shot it. |
+| "I know what the columns are called" | You don't. Check with `{{ s_schema }}`, `{{ s_schema_search }}`, or `{{ s_execute_query }}`. |
+| "Validation is slow, I'll do it at the end" | Validation is instant. Skipping it costs more time debugging later. |
+| "It's just a quick chart, no need for variables" | Variables cost nothing and enable caching. Use them. |
+| "User wants 15 charts on one dashboard" | 8 max. Propose splitting into focused dashboards. |
+
+## Red Flags — STOP
+
+- About to write SQL without having explored the actual schema first
+- Building more than one new chart before validating the previous one
+- Dashboard has more than 8 visualizations
+- A chart exists without a clear question it answers
+- Using hardcoded values that should be variables
+- Delivering without running the self-review checklist

dataface/ai/skills/dashboard-build/examples/_smoke.yml

@@ -0,0 +1,15 @@
+title: Smoke Test Dashboard
+queries:
+  revenue:
+    columns: [month, amount]
+    values:
+      - [Jan, 1000]
+      - [Feb, 1200]
+      - [Mar, 900]
+charts:
+  kpi:
+    query: revenue
+    type: kpi
+    value: amount
+rows:
+  - kpi

dataface/ai/skills/dashboard-design/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: dashboard-design
+kind: workflow
+description: >
+  Design principles for Dataface dashboards — at-a-glance monitoring displays.
+  Use when choosing chart types, designing dashboard layouts, picking colors,
+  deciding dashboard vs report, or when the user says 'what chart type',
+  'how should I lay this out', 'dashboard design'. Covers information
+  hierarchy, chart selection, layout patterns, and visual design. Do NOT
+  use for reports or narrative analyses (use report-design). Do
+  NOT use for the build-test-iterate workflow (use
+  dashboard-build). Do NOT use for fixing errors (use
+  dataface-troubleshooting).
+metadata:
+  author: fivetran
+---
+
+# Dashboard Design
+
+Design dashboards for **at-a-glance monitoring** — clear, scannable, action-oriented displays.
+
+> Implementing in YAML? Switch to `{{ s_skill_build }}` for the build-test-iterate workflow.
+
+## Dashboard vs. Report
+
+| | Dashboard | Report |
+|--|-----------|--------|
+| **Purpose** | Monitor status at a glance | Answer a question, tell a story |
+| **Frequency** | Daily / continuous | One-time or periodic |
+| **Text** | Minimal — titles and labels | Extensive — narrative + recommendations |
+| **Charts** | Primary content | Supporting evidence for the narrative |
+| **Interaction** | Scan in seconds | Read in minutes |
+
+If the user needs a narrative analysis, use the `report-design` skill instead.
+
+## Core Principles
+
+1. **Single screen** — no scrolling. If it doesn't fit, split into multiple dashboards.
+2. **Scannable in seconds** — a glance should convey status.
+3. **Every element earns its place** — remove anything that doesn't aid understanding.
+4. **Context for every number** — a number without comparison (trend, target, prior period) is meaningless.
+5. **Purpose-driven** — every chart answers a specific question.
+
+## Metadata Requirement
+
+Whenever you output or edit Dataface YAML, add `description` metadata:
+
+- `queries.*.description` for query intent
+- `charts.*.description` for chart intent
+- `variables.*.description` for filter semantics
+- Layout object `description` fields (`rows`/`cols`/`grid.items`/`tabs.items`) when they add context
+
+Descriptions should be concise and optimized for AI retrieval.
+
+## Thinking Process
+
+Before designing, work through these in order:
+
+### 1. Audience & Purpose
+
+- **Who** views this? (executive, analyst, operator)
+- **When** do they view it? (morning standup, weekly review, always-on monitor)
+- **What decision** does this inform?
+
+### 2. Information Hierarchy
+
+- What is the **#1 most important metric**? → top-left, largest
+- What are the **3-5 supporting KPIs**? → KPI row
+- What **trends** matter? → line/area charts
+- What **comparisons** are useful? → bar charts
+- What **detail** supports drill-down? → tables at the bottom
+
+### 3. Chart Selection
+
+| Question | Chart Type | Notes |
+|----------|-----------|-------|
+| Current value? | `kpi` | Big number, prominent position |
+| Trending over time? | `line` | Continuous data, time on x-axis |
+| Category comparison? | `bar` | Categorical x-axis, include zero baseline |
+| Composition over time? | `area` (stacked) | Parts of a whole changing |
+| Portion of whole? | `pie` | **Only for 2-3 segments** — use bar for more |
+| Relationship? | `scatter` | Two numeric variables |
+| Precise values? | `table` | When exact numbers matter |
+
+**Avoid:**
+- Pie for >3 categories (humans compare angles poorly — use bar)
+- Multiple chart types for visual variety (consistency aids scanning)
+- Scrolling layouts (if it scrolls, it's a report)
+
+### 4. Layout — Inverted Pyramid
+
+Most important information first, following Western reading pattern (top-left → bottom-right):
+
+```
+┌──────────────────────────────────────────────┐
+│  KPI 1  │  KPI 2  │  KPI 3  │  KPI 4       │  ← HEADLINE
+├──────────────────────────────────────────────┤
+│  Primary trend chart (line/area)             │  ← STORY
+├──────────────────────┬───────────────────────┤
+│  Comparison chart    │  Comparison chart     │  ← CONTEXT
+├──────────────────────┴───────────────────────┤
+│  Detail table (if needed)                    │  ← EVIDENCE
+└──────────────────────────────────────────────┘
+```
+
+- **4-8 total visualizations maximum**
+- Related metrics grouped by proximity
+- Consistent styling throughout
+
+### 5. Color & Visual Design
+
+- **Gray is default** — muted everything, ONE accent color for emphasis
+- **Color carries meaning** — same color = same meaning everywhere
+- **Direct labels** on charts when possible, not separate legends
+- **Maximize data-ink ratio** — every pixel should represent data
+
+### 6. Numeric Display
+
+Apply standard numeric-display judgment (two-numeral rule, no false precision, tabular numerals in columns). Dataface-specific defaults:
+
+- **Use format aliases, not raw d3 specs.** `format: currency_whole`, `format: percent`, `format: percent_delta`, `format: integer`, `format: compact`. Raw d3 (`"$,.0f"`) only when no alias fits.
+- **Drop cents above $10.** `format: currency_whole` is the dashboard default. Reserve `format: currency` (with cents) for reconciliation surfaces — billing, financial statements.
+- **Notation family: analytic for chrome, narrative for prose.** Analytic (`$2.5 M`, space, uppercase K/M/B) for axes, KPIs, tables, tooltips. Narrative (`$2.5mn`, no space, lowercase) only for text cards, titles, annotations. Independent of theme choice.
+- **Zero strips trailing decimals even when siblings have them.** A `$0` KPI uses `currency_whole` even if its partner uses `currency`. A `0%` KPI uses `percent_whole` even if its partner uses `.2%`. The rule generalizes to any unit.
+- **Percent precision is a group decision.** Default by magnitude: ≥20% → `.0%`; 1–20% → `.1%`; <1% → `.2%`. **Modulate by surface:** a single KPI or short rail can afford one more decimal; a long table column or axis wants the simpler form. **Override:** when tenths carry signal regardless of magnitude (A/B rates, churn, conversion in a tight range), use `format: ".2%"`.
+- **Compaction is a group decision, not per-value.** Compact when ≥4 similar-magnitude values exceed 10,000, or when surface density demands it. Adjacent surfaces showing the same metric may compact differently — a reconciliation table can show full precision while the headline KPI uses `currency_compact`.
+- **NULL renders as `—` (em-dash), never `0`.** Different claims about the data.
+- **Tables anchor the currency symbol.** Default `symbol_mode: anchors` — first row carries the `$`, rows below don't.
+
+### 7. Variables & Interactivity
+
+Add variables when the dashboard serves different time windows or segments:
+
+- Date ranges → `daterange` input
+- Categorical filters → `select` input
+- Set sensible defaults (last 30 days, most common category)
+- **NOT for executive dashboards** — those show the single most important view
+
+## Dashboard Patterns
+
+### Executive Dashboard
+4-6 KPIs → main trend → 2-3 breakdowns. No interaction. Show the single most important view.
+
+### Operational Dashboard
+Status KPIs with alerts → recent activity → issues table. Emphasize what needs attention now.
+
+### Analytical Dashboard
+KPIs → trends with filters → comparisons across dimensions → detail table. Include `variables:` for interactive filtering.
+
+## Quality Checklist
+
+Before delivering:
+
+- [ ] Fits on one screen (≤8 visualizations, no scrolling)
+- [ ] KPIs are first and most prominent (top row)
+- [ ] Every number has context (comparison, trend, or target)
+- [ ] Chart types match the analytical question
+- [ ] Related metrics grouped by proximity
+- [ ] Color is purposeful, not decorative
+- [ ] Titles are informative ("Revenue by Region, Last 30 Days" not "Chart 1")
+- [ ] User's most important question answered at a glance
+- [ ] Query/chart/variable/layout `description` metadata is filled for AI context
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Too many charts (>8) | Split into multiple focused dashboards |
+| KPIs without context | Add comparison period, trend, or target |
+| Pie chart with 7 segments | Use a bar chart instead |
+| Decorative color | Color must encode data or meaning |
+| Generic titles | Titles should state what the chart answers |
+| Scrolling dashboard | Reduce charts or split dashboards |
+
+## Rationalizations to Resist
+
+| Excuse | Reality |
+|--------|---------|
+| "User asked for 12 metrics on one page" | 8 max. Propose splitting into focused dashboards. |
+| "Pie chart is fine for 6 categories" | It's not — humans compare angles poorly. Use bar. |
+| "The legend explains the colors" | Direct labels are always better than legends. |
+| "More charts = more value" | More charts = more noise. Each must earn its place. |

dataface/ai/skills/dashboard-review/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: dashboard-review
+kind: workflow
+description: >
+  Primary entry point for reviewing a Dataface face. Runs
+  `dashboard-structural-review` first, then runs `dashboard-visual-review` when
+  the user asked for visual review or when structural surfaced ambiguous
+  "feels wrong" findings. Synthesizes both passes into a single ranked,
+  deduplicated findings list. Use when asked to 'review this dashboard',
+  'review this face', 'is this dashboard good', or after building / editing a
+  face before delivery. Do NOT use when only one pass is needed — invoke the
+  leaf skill directly. Do NOT use for comparing two versions of a face (use
+  the looker-compare-diff pattern).
+metadata:
+  author: fivetran
+---
+
+# Dashboard Review
+
+Orchestrate `dashboard-structural-review` and `dashboard-visual-review` into a
+single ranked findings list. This is the default entry point — most "review"
+requests should land here, not on either leaf skill.
+
+## When to use
+
+- Any open-ended "review this dashboard" request
+- Pre-delivery final pass
+- After a substantive edit (new chart, new query, layout change)
+
+## When NOT to use
+
+- The user explicitly asked for only structural OR only visual — invoke that
+  leaf skill directly
+- Comparing two versions of a face — use the `looker-compare-diff` pattern
+
+## Protocol
+
+### Step 1: Always run structural review
+
+Invoke `dashboard-structural-review` first. It's cheap (no rendering, no
+vision tokens) and catches every problem that's visible in the YAML.
+
+### Step 2: Decide whether to run visual review
+
+Run `dashboard-visual-review` when **any** of the following is true:
+
+- The user asked for visual review explicitly ("how does it look", "review the
+  rendered output", "visual review", "check the design")
+- Structural review surfaced a finding that hints at a visual problem (KPI
+  precision, generic title that may collide with axis labels, dense chart
+  count that may crowd the canvas)
+- Structural review returned `**No findings.**` and the user asked for a
+  thorough review — do the visual pass to confirm
+
+Skip visual review when:
+
+- Structural review surfaced `blocker` findings — fix those first; rendering
+  may be misleading until the YAML is correct
+- The user asked for a quick / cheap review
+- `{{ s_validate_dashboard }}` failed inside
+  structural review — there's nothing valid to render yet
+
+### Step 3: Synthesize
+
+Merge findings from both passes into a single list:
+
+1. **Deduplicate.** If both passes surface the same issue (e.g. structural
+   notes the KPI has no format spec and visual notes the rendered number is
+   `1247392.74`), keep the more concrete finding.
+2. **Order by severity.** All `blocker` findings before `warning` before
+   `nit`. Within a severity, keep the order each pass produced.
+3. **Cap at 5** by default. If you have to drop findings, drop `nit` first,
+   then `warning`. Never drop a `blocker`.
+4. **Tag the source** so the user knows which pass surfaced what.
+
+## Output format
+
+```markdown
+**Dashboard review**
+
+- `blocker` [structural] `charts.revenue_kpi`: query returns 12 rows but
+  `type: kpi` requires 1. Aggregate with `SUM()`.
+- `warning` [visual] `charts.regions_bar`: x-axis labels overlap at rendered
+  width. Rotate to -45° or shorten.
+- `warning` [structural] `queries.orders`: no `description:` field. Add one
+  sentence stating intent.
+- `nit` [visual] `charts.users_pie`: muted palette would reduce visual noise.
+
+**Passes run:** structural, visual
+**Skipped:** —
+```
+
+If neither pass found anything: emit `**Dashboard review: no findings.**`.
+
+If a pass was skipped, name it in `**Skipped:**` with a one-phrase reason
+(`Skipped: visual — blockers in structural pass`).
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Running visual review before structural | Always structural first. Visual depends on a render that won't be meaningful until the YAML is valid. |
+| Skipping structural because "it's just visual" | The YAML is the source of truth — never skip structural. |
+| Padding the synthesized list to fill a cap | If both passes agreed there are only 2 findings, return 2. |
+| Forgetting to tag pass source | The user needs `[structural]` / `[visual]` to know where to look. |
+
+## Rationalizations to resist
+
+| Excuse | Reality |
+|---|---|
+| "User said 'review' — they probably only want a quick check" | Default to thorough. The user can ask for cheap explicitly. |
+| "Visual review is slow, let's skip it" | If a render is fast on this face (most are), do both passes by default. Cost is a real concern only at scale. |
+| "Both passes are saying the same thing, I'll keep both" | Dedupe. Showing the same issue twice erodes trust. |