[MaxGhenis]

The operating procedure for PolicyEngine's pre-publish comparables gate: before an analysis is listed on policyengine.org, or featured in a newsletter, social campaign, webinar or press push, every external estimate of what it estimates is found, recorded in PolicyEngine/policyengine-scorecard, compared with the analysis's own figures, and every gap over the threshold is explained.

What it adds

• skills/policyengine-comparables-review/: the review, step by step.
  • Scaffold a record, pin every figure the page publishes (with its identity: basis, programme, fiscal year), search every producer on the scorecard's data/comparables/producers.json, stage what is found, compare like with like or set a claim beside its nearest estimate with a stated mismatch, and explain every gap over the threshold with a cited cause.
  • The fields a record needs, with the childcare record as the worked example, and which harvest rules apply.
  • The evasions never to use (leaving a figure out, a null metric, a chart reading for a printed figure, choosing a period to avoid a match, relabelling a miss as a mismatch) and a reviewer checklist for what the validator cannot see (every published figure pinned, pe_missing true, bases support causes, none_found spot-checked, hashes recomputed).
  • US guidance: sign phrasings that orient, fiscal versus calendar years, budget-window totals, state fiscal notes.
  • The household-calculator path (searched, no fixed estimate), "Before a push" (a pending gap blocks it, newsletters and the homepage banner alike), the after-publication re-harvest, and bill-tracker scores (reviewed before dispatch, recorded as registry.kind: tracker).
  • What app-v2 checks on the day a change lists an entry (search age that day, current results, no gap pending), the proxied-page rule, deployments, record's latest-search default, report running while gaps are unexplained, and that window totals are staged, not compared.
  • Commands as CI runs them (uv run, CI's test dependencies), including committing every feed the build rewrites.
• references/search-brief.md: a self-contained brief for running the search as a background job, for any agent with web search, a writable workspace and gh push access (PolicyEngine's internal Subfleet lanes need -s workspace-write). It covers all four search kinds, pushes a draft PR even when a gap is unexplained, and writes a pending cause that cites its tracking issue.
• /comparables-review: the Claude command.
• Wiring: /deploy-dashboard runs the review before anything is public, wires the zone through appZoneRoutes.ts and uses a registry template app-v2 accepts; /new-tool keeps the repository private and undeployed until the review merges; /create-dashboard's next steps, report-logger's draft research posts, the policyengine-writing checklist, policyengine-tools, policyengine-content, /generate-content and the content orchestrator (freshness before a push), /reform-pipeline (both routes reviewed, the tracker route before dispatch), policyengine-prior-scores and presets/scorekeepers.yaml (the scorecard list is the one this review must cover), docs/when-to-use.md and the skills README.
• Bundles: complete, analysis-tools, dashboard-builder and app-development carry the skill and command. Version 4.0.2 → 4.1.0.
• dashboard/src/data/manifest.json is regenerated so the guide's command check sees /comparables-review. scripts/build_manifest.py orders some lists differently on each run, so most of that file's diff is reordering; main's copy was already out of date.

Companion PRs and merge order

1. Record every comparable external estimate before an analysis is published policyengine-scorecard#208: the producer list, validator, threshold, index, first record and the commands this skill runs.
2. Require a comparables record on research entries after the cutover policyengine-app-v2#1380: the registry block and CI gate.
3. Refuse to send an edition whose analyses lack a fresh comparables search newsletters#29: the freshness check before a send.
4. This PR, last, so every check it describes is on main when it lands.

Checks

• uv run pytest --ignore=tests/test_skill_examples.py: 178 passed.
• scripts/build_claude_wrapper.py: builds; the skill, references/search-brief.md and commands/comparables-review.md are present.
• Description 945 characters.

After merge, policyengine-app-v2's ai-agents stats need refreshing (24 skills, 36 agents, 21 commands, 8 bundles): PolicyEngine/policyengine-app-v2#1397.

🤖 Generated with Claude Code