@pixerate/editor 0.223.0 → 0.223.2

package/skills/pixerate-chart-choose-and-build/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: pixerate-chart-choose-and-build
+description: The chart building workflow in the Pixerate chart editor - starting from the question the chart answers, choosing the chart type for it (change over time, comparison, part of a whole, distribution, relationship, flow, geography), loading clean data in order, honest axes (bars from zero, log only for orders of magnitude), units and number formats, colours that colour-blind readers can tell apart, and checking before handing it over. Use when asked to make, build, create, choose, recommend or fix a chart or graph, visualise or plot data, pick the right chart, or make a chart clearer, more honest or accessible, or when recommend_chart, set_chart_data, update_chart or check_chart_colors are available. Load with pixerate-chart, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-chart
+---
+
+# Choosing and building a chart
+
+A chart answers one question. Name the question first ("how did revenue change over the
+year?", "which region sells most?"), and the type, the order of the data, the axes and the
+title follow from it. Build in few calls: data in one, style in one, then check the warnings,
+the colours and the numbers before anyone sees it.
+
+This skill is the method. `pixerate-chart` has the full tool reference; for titles, highlights,
+reference lines and notes that make the point, see `pixerate-chart-annotate`.
+
+## Goal and quality bar
+
+- The type fits the question (see the decision table).
+- The data is in a meaningful order: time in calendar order, categories sorted by value unless
+  they have a natural order.
+- Axes are honest: bars and areas start at zero; a log scale only when values span orders of
+  magnitude, and labelled as such; a second axis only for a second unit.
+- Units are stated (axis title or number `format`); the title says what the chart shows.
+- Colours pass `check_chart_colors` (`ok: true`) and there are at most about seven series
+  colours.
+- `get_chart` `summary.warnings` and `issues` are empty.
+
+## Inputs to confirm
+
+- **The question** the chart must answer, and for whom (a report, a slide, a dashboard).
+- **The data**: where it is (pasted, CSV, a spreadsheet, an Office file) and its units.
+- **House style** if the host has one (`check_chart_style`).
+
+## Working method
+
+1. **Read.** `get_chart` (the spec, the data table, warnings); `list_file_charts` when the
+   data is in an open Office file.
+2. **Name the question and choose the type.** `recommend_chart` suggests types for the data;
+   check its suggestion against the question (see the table).
+   **Check:** you can say the question in one sentence and why this type answers it.
+3. **Load clean data in one call.** `set_chart_data` with categories in the right order and one
+   series per measure (or `import_chart_csv`); numbers as numbers, gaps as `null`.
+   **Check:** `get_chart` `spec.categories` and each series' `values` line up as intended.
+4. **Style in one call.** `update_chart` with `type`, `title`, axis `title` and `format`,
+   `legend`, `stacking`, `orientation`, `dataLabels`. Bars from zero (`yAxis.min` null or 0).
+   **Check:** `get_chart` spec; `summary.description` reads as the chart you meant.
+5. **Colours.** `check_chart_colors`; fix failing pairs with `update_chart_series` `color` (a
+   palette such as `#4269d0` / `#efb118` separates for most colour vision), or
+   `apply_chart_preset` for a tested palette.
+   **Check:** `check_chart_colors` `ok: true`.
+6. **Look.** `render_chart` once after the batch; fix anything that does not read.
+
+## Decision table
+
+| Question | Type |
+| --- | --- |
+| How did it change over time? | `line` (one or a few series), `area` for totals, columns for few periods |
+| Which is biggest? Compare categories | `bar`, horizontal for long labels, sorted by value |
+| Part of a whole (few parts) | `pie` or `donut` (at most five slices), or a stacked bar |
+| Part of a whole, nested | `treemap`, `sunburst` (`set_chart_tree`) |
+| How are values distributed? | `histogram`, `box` |
+| Do two measures relate? | `scatter`, `bubble` for a third measure |
+| Before and after per category | `slope` |
+| Contributions to a total | `waterfall` |
+| Flows between stages | `sankey` (`set_chart_links`), `funnel` for one path |
+| Survey answers | `likert` |
+| By region on a map | `choropleth` |
+
+## Recipes
+
+**Trend over time.** `set_chart_data` with categories in calendar order → `update_chart`
+`{ type: "line", title, yAxis: { title: "Revenue (USD thousands)" } }` → `get_chart`.
+
+**Colour-blind fix.** `check_chart_colors` → `update_chart_series` `color` on the clashing series
+→ `check_chart_colors` again.
+
+**Honest bars.** `update_chart` `{ yAxis: { min: 0 } }`; when small differences matter, show the
+differences themselves (a bar of the change) or a dot plot rather than a cut axis.
+
+## Pitfalls
+
+- **Truncated bar axes** exaggerate differences; bars start at zero.
+- **Pie charts with many or similar slices** cannot be read; use a sorted bar.
+- **Red and green** as the only distinction fail for the most common colour-vision deficiency.
+- **Unsorted categories** without a natural order hide the ranking.
+- **Mixed units on one axis**, or a second axis for the same unit, mislead.
+- **Missing units** leave the reader guessing; put them in the axis title or format.
+
+## Tools used
+
+- `get_chart`, `render_chart`: the spec, data table, warnings, and a picture
+- `recommend_chart`: types that suit the data
+- `set_chart_data`, `import_chart_csv`, `transpose_chart`: load the data in order
+- `update_chart`, `update_chart_series`, `apply_chart_preset`: type, titles, axes, formats and colours
+- `check_chart_colors`, `check_chart_style`: colour-blind and house-style checks
+- `list_file_charts`, `load_file_chart`: data from open Office files
+- `undo_chart`: take back a step

package/skills/pixerate-chart-choose-and-build/evals/colour-blind-safe.json

@@ -0,0 +1,113 @@
+{
+	"prompt": "Some of our readers are colour-blind and can't tell the two years apart in this chart. Fix the colours without changing the data.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"North",
+						"South",
+						"East",
+						"West"
+					],
+					"series": [
+						{
+							"name": "2025",
+							"values": [
+								12,
+								15,
+								9,
+								11
+							],
+							"color": "#d62728"
+						},
+						{
+							"name": "2026",
+							"values": [
+								14,
+								13,
+								12,
+								15
+							],
+							"color": "#2ca02c"
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "bar",
+					"title": "Sales by region"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the colours pass the colour-blind check",
+			"tool": "check_chart_colors",
+			"expect": {
+				"ok": true
+			}
+		},
+		{
+			"why": "the data is unchanged",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"categories": [
+						"North",
+						"South",
+						"East",
+						"West"
+					],
+					"series": [
+						{
+							"name": "2025",
+							"values": [
+								12,
+								15,
+								9,
+								11
+							]
+						},
+						{
+							"name": "2026",
+							"values": [
+								14,
+								13,
+								12,
+								15
+							]
+						}
+					]
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "check_chart_colors"
+		},
+		{
+			"tool": "update_chart_series",
+			"args": {
+				"series": "2025",
+				"color": "#4269d0"
+			}
+		},
+		{
+			"tool": "update_chart_series",
+			"args": {
+				"series": "2026",
+				"color": "#efb118"
+			}
+		},
+		{
+			"tool": "check_chart_colors"
+		}
+	]
+}

package/skills/pixerate-chart-choose-and-build/evals/honest-baseline.json

@@ -0,0 +1,81 @@
+{
+	"prompt": "This bar chart makes the differences between teams look huge, but they're small. Make it honest.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"Team A",
+						"Team B",
+						"Team C",
+						"Team D"
+					],
+					"series": [
+						{
+							"name": "Satisfaction (%)",
+							"values": [
+								92,
+								95,
+								94,
+								97
+							]
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "bar",
+					"title": "Satisfaction by team",
+					"yAxis": {
+						"min": 90,
+						"max": 98
+					}
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "bars start at zero (or the chart is no longer bars)",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"$expr": "v.type !== 'bar' || v.yAxis.min === null || v.yAxis.min === 0"
+				}
+			}
+		},
+		{
+			"why": "the data is unchanged",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"series": [
+						{
+							"values": [
+								92,
+								95,
+								94,
+								97
+							]
+						}
+					]
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "update_chart",
+			"args": {
+				"yAxis": {
+					"min": 0,
+					"max": 100
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-chart-choose-and-build/evals/trend-over-time.json

@@ -0,0 +1,175 @@
+{
+	"prompt": "This is our 2026 monthly revenue in thousands of US dollars, pasted in a muddle. Make a chart that shows how revenue changed over the year.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"Mar",
+						"Jan",
+						"Feb",
+						"Jun",
+						"Apr",
+						"May",
+						"Sep",
+						"Jul",
+						"Aug",
+						"Dec",
+						"Oct",
+						"Nov"
+					],
+					"series": [
+						{
+							"name": "Revenue",
+							"values": [
+								51,
+								42,
+								45,
+								61,
+								48,
+								55,
+								70,
+								58,
+								64,
+								82,
+								68,
+								75
+							]
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "pie"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "a line or area chart for change over time",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"type": {
+						"$in": [
+							"line",
+							"area"
+						]
+					}
+				}
+			}
+		},
+		{
+			"why": "months in calendar order, with their own values",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"categories": [
+						"Jan",
+						"Feb",
+						"Mar",
+						"Apr",
+						"May",
+						"Jun",
+						"Jul",
+						"Aug",
+						"Sep",
+						"Oct",
+						"Nov",
+						"Dec"
+					],
+					"series": [
+						{
+							"values": [
+								42,
+								45,
+								51,
+								48,
+								55,
+								61,
+								58,
+								64,
+								70,
+								68,
+								75,
+								82
+							]
+						}
+					]
+				}
+			}
+		},
+		{
+			"why": "a title and a value axis that says the unit",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"title": {
+						"$match": "\\S"
+					},
+					"yAxis": {
+						"$expr": "/usd|\\$|dollar/i.test(v.title) || v.format.style === 'currency' || /\\$/.test(v.format.prefix || '')"
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "get_chart"
+		},
+		{
+			"tool": "set_chart_data",
+			"args": {
+				"categories": [
+					"Jan",
+					"Feb",
+					"Mar",
+					"Apr",
+					"May",
+					"Jun",
+					"Jul",
+					"Aug",
+					"Sep",
+					"Oct",
+					"Nov",
+					"Dec"
+				],
+				"series": [
+					{
+						"name": "Revenue",
+						"values": [
+							42,
+							45,
+							51,
+							48,
+							55,
+							61,
+							58,
+							64,
+							70,
+							68,
+							75,
+							82
+						]
+					}
+				]
+			}
+		},
+		{
+			"tool": "update_chart",
+			"args": {
+				"type": "line",
+				"title": "Revenue grew through 2026",
+				"yAxis": {
+					"title": "Revenue (USD thousands)"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-spreadsheet/SKILL.md

@@ -21,6 +21,8 @@ For these jobs, load the workflow skill too: it has the method, the checks betwe
 the pitfalls, and uses the tools below.
 
 - `pixerate-spreadsheet-clean-import`: tidying imported or pasted data: structure, headers, types, dates, duplicates.
+- `pixerate-spreadsheet-analysis`: summaries, growth, shares and rankings as formulas that reconcile.
+- `pixerate-spreadsheet-financial-model`: inputs, consistent calculation rows, scenarios and audits.
 
 ## Working method
 

package/skills/pixerate-spreadsheet-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: pixerate-spreadsheet-analysis
+description: The analysis workflow in a Pixerate spreadsheet - turning tidy data into answers with live formulas - summary tables by category (SUMIFS, COUNTIFS, AVERAGEIFS), distinct lists with UNIQUE, ranked and filtered views with SORT and FILTER, period totals and growth, shares of a total, checks that the summary reconciles with the data, and handing the result to a chart. Use when asked to summarise, total, count, average, group, pivot, rank, compare, break down or analyse data in a spreadsheet, work out growth or percentages, find the top items, or prepare numbers for a chart, or when get_range and set_range are available. Load with pixerate-spreadsheet, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-spreadsheet
+---
+
+# Analysing data in a spreadsheet
+
+An analysis is a set of formulas that answer a question from the data and keep answering it
+when the data changes. Start from tidy data (one header row, one record per row; clean it first
+with `pixerate-spreadsheet-clean-import` if needed), put each summary in its own block beside or
+below the data, and make every number a formula over the data, never a typed result.
+
+This skill is the method. `pixerate-spreadsheet` has the full tool reference and the supported
+functions; for the chart that shows the result, see `pixerate-chart-choose-and-build`.
+
+## Goal and quality bar
+
+- Every result is a formula over the data (`SUMIFS`, `COUNTIFS`, `AVERAGEIFS`, `FILTER`,
+  `UNIQUE`, `SORT`), with absolute references to the data range, so it updates and can be
+  checked.
+- Summaries have a header row and one row per group; nothing is typed over a formula.
+- The summary reconciles: group totals add up to the data's total.
+- No formula errors (`get_range` `errors` empty); expected errors handled explicitly
+  (`IFERROR` around a division by a possible zero), and blanks where a value does not apply.
+- The data itself is untouched.
+
+## Inputs to confirm
+
+- **The question** (totals by region, growth by month, top products) and the measure.
+- **Where the result goes** (a cell such as G1, or below the data).
+- **Groups:** a fixed list the user gives, or every distinct value in the data (`UNIQUE`).
+
+## Working method
+
+1. **Read the data.** `get_range` the header and a sample; note the data range, which column is
+   the group and which the measure, and whether it is tidy.
+   **Check:** one header row, one record per row, numbers as numbers.
+2. **Lay out the summary** in an empty area: a header row, then one row per group. List groups
+   yourself when there are few and fixed, or `=UNIQUE(B2:B500)` for every value (leave room for
+   it to spill).
+3. **Write the formulas in one block.** `set_range` with the header and a formula per row, each
+   with absolute data references and a relative group cell: `=SUMIFS($D$2:$D$500,$B$2:$B$500,G2)`.
+   **Check:** the returned `errors` is empty.
+4. **Reconcile.** Add a total row (`=SUM(H2:H5)`) and compare it with `=SUM($D$2:$D$500)`; for
+   counts, with `=COUNTA` of the key column.
+   **Check:** they match; if not, a group is missing or a value is text.
+5. **Derived measures**: growth `=B3/B2-1` (blank for the first period), share `=H2/SUM($H$2:$H$5)`,
+   rank `=RANK(H2,$H$2:$H$5)`, ranked lists `=SORT(G2:H5,2,-1)`.
+   **Check:** `get_range` values match a hand calculation for one row.
+6. **Hand over.** Tell the user where the summary is and what each column means; to chart it,
+   pass the summary block (categories and values) to the chart editor's `set_chart_data`.
+
+## Decision table
+
+| Question | Formula |
+| --- | --- |
+| Total per group | `SUMIFS(measure, group_range, group)` |
+| How many per group | `COUNTIFS(group_range, group)` |
+| Average per group | `AVERAGEIFS(measure, group_range, group)` |
+| Two conditions (region and month) | `SUMIFS` with two criteria pairs |
+| Every distinct group | `UNIQUE(group_range)`, spilled |
+| Rows that meet a condition | `FILTER(data, condition)` |
+| Top items | `SORT` (or `SORTBY`) the summary by its total, descending |
+| Change from the previous period | `=this/previous-1`, first period blank |
+| Share of total | `=value/SUM($total_range)` |
+
+## Recipes
+
+**Totals by region at G1.** `set_range` from G1 with `[["Region", "Total"], ["North",
+"=SUMIFS($D$2:$D$11,$B$2:$B$11,G2)"], ...]` (each row's formula pointing at its own G cell).
+
+**Month-over-month growth in C.** `set_range` from C1: `[["Growth"], [null], ["=B3/B2-1"],
+["=B4/B3-1"], ...]`.
+
+**Orders and average per product.** Columns `=COUNTIFS($C$2:$C$11,G2)` and
+`=AVERAGEIFS($D$2:$D$11,$C$2:$C$11,G2)`.
+
+## Pitfalls
+
+- **Typed results.** A number typed into a summary does not update; always a formula.
+- **Relative data references.** `D2:D11` shifts when you write the formula down; use `$D$2:$D$11`.
+- **Text numbers** in the measure column are skipped by `SUMIFS`; clean the data first.
+- **Spills blocked**: `UNIQUE`, `FILTER` and `SORT` need empty cells below and to the right.
+- **Totals inside the data range** double-count; keep summaries outside it.
+- **0 for "no previous period"** misleads averages; leave it blank.
+- **`set_range` writes formulas as given**: write each row's own references.
+
+## Tools used
+
+- `get_range`: read the data and check every result and error
+- `set_range`: write summary blocks with headers and formulas, one undo step
+- `set_cell`: fix one formula
+- `insert_columns`, `insert_rows`: make room for a summary
+- `undo_spreadsheet`: take back a step