diff --git a/bundles/analysis-tools.json b/bundles/analysis-tools.json index 8cb9b3b..6ce0e13 100644 --- a/bundles/analysis-tools.json +++ b/bundles/analysis-tools.json @@ -2,7 +2,7 @@ "name": "analysis-tools", "description": "Policy analysis and research - impact studies, dashboards, notebooks, and visualizations", "category": "analysis", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "analysis", "research", diff --git a/bundles/api-development.json b/bundles/api-development.json index 0320eb7..666d510 100644 --- a/bundles/api-development.json +++ b/bundles/api-development.json @@ -2,7 +2,7 @@ "name": "api-development", "description": "API development - Flask endpoints, caching, services, and integration patterns", "category": "development", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "api", "flask", diff --git a/bundles/app-development.json b/bundles/app-development.json index 269406e..160d545 100644 --- a/bundles/app-development.json +++ b/bundles/app-development.json @@ -2,7 +2,7 @@ "name": "app-development", "description": "React app development - app-v2, standalone tools, Vercel deployment, and PolicyEngine-specific patterns", "category": "development", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "react", "frontend", diff --git a/bundles/complete.json b/bundles/complete.json index ed4b8b1..4a55aa4 100644 --- a/bundles/complete.json +++ b/bundles/complete.json @@ -2,7 +2,7 @@ "name": "complete", "description": "Complete PolicyEngine knowledge base - all agents, commands, and skills for users, analysts, and contributors", "category": "complete", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "complete", "all", diff --git a/bundles/country-models.json b/bundles/country-models.json index 9e4912a..0e1f95e 100644 --- a/bundles/country-models.json +++ b/bundles/country-models.json @@ -2,7 +2,7 @@ "name": "country-models", "description": "Complete multi-agent workflow for implementing government benefit programs in PolicyEngine country packages", "category": "development", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "tax", "benefits", diff --git a/bundles/dashboard-builder.json b/bundles/dashboard-builder.json index 00d418c..51da779 100644 --- a/bundles/dashboard-builder.json +++ b/bundles/dashboard-builder.json @@ -2,7 +2,7 @@ "name": "dashboard-builder", "description": "Orchestrated AI workflow for creating PolicyEngine dashboards from natural-language descriptions", "category": "development", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "dashboard", "calculator", diff --git a/bundles/data-science.json b/bundles/data-science.json index 6d6f99d..ab99d69 100644 --- a/bundles/data-science.json +++ b/bundles/data-science.json @@ -2,7 +2,7 @@ "name": "data-science", "description": "Data analysis, survey enhancement, imputation, calibration, and microdata utilities", "category": "data", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "data", "microdata", diff --git a/bundles/essential.json b/bundles/essential.json index 12f75ab..a031766 100644 --- a/bundles/essential.json +++ b/bundles/essential.json @@ -2,7 +2,7 @@ "name": "essential", "description": "Essential PolicyEngine knowledge for all users - understanding the platform, using the web app, and basic concepts", "category": "getting-started", - "version": "4.0.2", + "version": "4.0.3", "keywords": [ "beginner", "users", diff --git a/skills/policyengine-design/SKILL.md b/skills/policyengine-design/SKILL.md index 5747662..3d662ae 100644 --- a/skills/policyengine-design/SKILL.md +++ b/skills/policyengine-design/SKILL.md @@ -149,8 +149,17 @@ automatically. Do not claim built-in dark mode at this version. PolicyEngine-contributed; see the policyengine-tools skill for the version gate and the `domain={["auto", "auto"]}` pairing). Conventions: gains `--chart-1`; losses `--chart-5` or `--destructive`; neutral `--border`. -- **Plotly (Python maps/charts)** — house style: white `plot_bgcolor`/`paper_bgcolor`, Inter - font, teal series, logo bottom-right. Reference tokens by hex with a CSS-var comment. +- **Posts on policyengine.org:** draw charts as ```` ```chart ```` blocks, which the website + renders with ui-kit's chart defaults, Inter and the PolicyEngine watermark (Recharts for + `bar` and `waterfall`, a tile grid for `stateMap`). See policyengine-writing, "Figures, + covers and replication in posts", and app-v2's `chart-standards.md` under + `docs/engineering/`. The website builds Tailwind with the `tw:` prefix, so ui-kit + components that rely on unprefixed utility classes render unstyled there; style blog chart + parts inline with the `:root` token variables. Never embed matplotlib PNGs or Plotly JSON + in new posts. +- **Plotly (Python notebooks and standalone outputs, not posts)** — house style: white + `plot_bgcolor`/`paper_bgcolor`, Inter font, teal series, logo bottom-right. Reference + tokens by hex with a CSS-var comment. Sketch: ```python def format_fig(fig): diff --git a/skills/policyengine-writing/SKILL.md b/skills/policyengine-writing/SKILL.md index 2929f94..b8065bd 100644 --- a/skills/policyengine-writing/SKILL.md +++ b/skills/policyengine-writing/SKILL.md @@ -445,6 +445,80 @@ The reform dramatically slashes child poverty This is Montana's largest income tax cut in history ``` +## Figures, covers and replication in posts + +**Charts.** Draw every chart in a policyengine.org post as a ```` ```chart ```` block: a +JSON spec that the website renders with ui-kit's chart defaults, Inter and the PolicyEngine +watermark. `bar` and `waterfall` draw with Recharts; `stateMap` draws a US tile grid. In +policyengine-app-v2, the header comments of `BlogChart.tsx`, `BlogWaterfallChart.tsx` and +`BlogStateMap.tsx` (under `website/src/components/blog/`) document each spec, and the +engineering chart standards (`chart-standards.md` under `docs/engineering/`) cover the +details. Do not put matplotlib PNGs or Plotly JSON in new posts; when a post needs a chart +type the website lacks, add the type with tests first. Keep each chart's numbers identical +to the table or text beside it. + +**Charts elsewhere.** For a newsletter or social image, screenshot the chart as the live post +renders it (headless Chromium at 2x). A re-plot drifts from the post's labels, source line +and styling. + +**Covers.** Give research posts a photographic cover: a still life of relevant objects on a +light wooden table in soft natural light, with PolicyEngine teal (`#319795`, `#285E61`) only +in the objects, and nothing legible or recognizable: no text, numbers, currency, logos, +charts, portraits or faces. Generate it with an image model, inspect every object for stray lettering, and save +it as an 1800×840 WebP beside the post's other assets. Never use a chart or an infographic +as a cover. A product or tool launch may use a 1200×630 typographic card with no data +graphic instead. + +Prompt adapted from the one used for the graded 2025 SPM prediction post (swap the objects +for the post's subject): + +> Photorealistic editorial still life, high three-quarter angle, on a light oak table beside +> a window, soft diffuse morning light from the left, shallow depth of field. Objects grouped +> on the right two-thirds, leaving calm empty wood on the left: [objects]. Muted natural +> palette of warm wood, white paper and soft gray, with teal (#319795 and #285E61) appearing +> only in [two or three objects]. No legible text, numbers, currency, logos, charts or faces +> anywhere. Wide 2.14:1 landscape (1800×840). + +**Replication detail.** Name the model and its version in the body, as in the +methodological transparency example below. Put other package versions, script paths, commit +hashes and rerun steps in footnotes, so the body states what the numbers show and the +footnotes let a reader reproduce them. + +**Post dates.** Write `posts.json` dates with a time of day (`"2026-09-29 08:00:00"`). The +article page and research list parse a bare date as UTC midnight and show it as the previous +day to readers in US time zones. + +## Grading forecasts and explaining misses + +When a post grades a registered prediction or explains why the model missed: + +- **Grade what was registered.** Compare the registered quantity with the published figure + at the precision the source publishes, and give the published margins of error. When the + registration builds a level from a modeled change, grade the change as well. When the + published change is not statistically significant, say so. +- **Reruns show which assumptions matter.** A rerun that matches the published figure does + not identify the right inputs; say so beside the result. +- **Every rerun is a full model run** with the changed assumption entered as a model input. + Never estimate a rerun by scaling an earlier run's output or by adding effects from + separate runs. Name the run or runs behind each figure. +- **Lead with totals.** Splitting a change into parts (thresholds and resources, or one + income source at a time) can give different answers depending on the order of the steps. + Decompose each rerun from its own runs, report each order or the average over all orders, and do not + assign a remaining gap to one part on the strength of the baseline decomposition. +- **Compare survey years with care.** The CPS reweights to new population controls, so the + weighted count of people in a group, or of benefit recipients, can jump for reasons that + have nothing to do with the economy. Compare amounts per recipient, hold the age mix fixed + when it shifts, and treat two survey years as separate cross-sections, not a panel. +- **Show sampling error before claiming a pattern.** A gradient across deciles or groups + needs a bootstrap or replicate-weight standard error. When the pattern sits within its + error, present a rerun built on it as a sensitivity check. +- **Name each rate exactly**: "CPI-U, annual average" or "January over January"; "per + recipient aged 66 and over, at the 2024 age mix". Use the publisher's label for a data + series; change it only after checking the primary source. +- **Review before publishing.** Have an independent reviewer check every number and + mechanism claim against the result files and the code, and review again after each round + of fixes. + ## Structure and Organization Follow a clear hierarchical structure with key findings up front. @@ -747,6 +821,10 @@ Before publishing, verify: - [ ] Introduce finished work fresh; keep development history in supporting records - [ ] Remove self-referential clauses, empty contrasts, and unintroduced names or roles - [ ] Check mechanism claims against the code, test, or primary source +- [ ] Draw charts as ```` ```chart ```` blocks; no chart PNGs or Plotly JSON in new posts +- [ ] Use a photographic cover with nothing legible, never a chart +- [ ] Name the model and its version in the body; put other package versions, script paths and rerun steps in footnotes +- [ ] For graded forecasts: totals first, order-dependent splits labeled, sampling error shown for any pattern ## Resources diff --git a/targets/claude/marketplace.template.json b/targets/claude/marketplace.template.json index 1b97c6b..ffb772b 100644 --- a/targets/claude/marketplace.template.json +++ b/targets/claude/marketplace.template.json @@ -1,7 +1,7 @@ { "$schema": "https://claude.ai/schemas/plugin-marketplace.json", "name": "policyengine-claude", - "version": "4.0.2", + "version": "4.0.3", "description": "Complete PolicyEngine knowledge base - for users, analysts, and contributors across the entire PolicyEngine ecosystem", "owner": { "name": "PolicyEngine",