dashboard-audit-toolkit

Write precise client-facing definitions of dashboard KPIs / metrics by reading the backing SQL, not the display label. Use when: (1) drafting an "explain this dashboard to a client" doc, tooltip, onboarding email, or page-by-page narration; (2) the user pushes back on a metric definition you wrote ("that's not what X means"); (3) you're about to describe what a KPI "means" using its rendered label, the variable name in Python, or the column alias in SQL; (4) writing release notes, ADRs, or methodology notes for a metric. Covers the two traps caught repeatedly: (a) display label diverges from underlying SQL (e.g. "Active Students" labels a query that is literally `COUNT(*) FROM predictions WHERE scoring_date = MAX(scoring_date) AND <term>_suppressed IS NULL` — i.e. "rows in today's scoring run, post-suppression"); (b) UI toggles (term, lookback, segment) silently re-parametrize the count, so the same number means different things depending on which pill is active.

GitHub auto-close on squash-merge only catches ONE issue per PR even when the PR title/body says "Closes #447, #448, #449, #450". The first issue closes; the rest stay OPEN. Use when: (1) you opened a PR with a title or body listing multiple "Closes #X, #Y, #Z" references, (2) the PR squash-merged successfully (`gh pr view N --json state` = MERGED), (3) `gh issue list --state open` shows some of the referenced issues are still OPEN. Root cause: GitHub's auto-close keyword parser binds one keyword to one issue; "Closes #447, #448" is interpreted as "Closes #447" plus an inline reference to #448. Fix: either (a) write one keyword per issue ("Closes #447. Closes #448. Closes #449.") in the PR body BEFORE merging, or (b) post-merge, run `gh issue close $N --comment "Closed by PR #M (squash-merge auto-close caught only one)"` for each leftover. Different from `pr-followup-commit-stranded-after-squash` (which covers stranded COMMITS, not stranded ISSUES). Saves a "why are my issues still open after merging the fix?

Diagnose "the dashboard shows the wrong number even though the backend payload has been correct for months." Use when: (1) auditing rendered numbers against a baked / cached / pre-aggregated payload table, (2) finding that the payload row in BQ / Redis / KV has the right value but the template renders a stale hardcoded literal (e.g. "~930 students" next to a payload that says cohort_size=94), (3) earlier PRs in the area updated copy / historical-rate language but never wired the headline integer to the payload key, (4) other surfaces on the same page DO read the payload correctly (proves the wiring pattern exists) but specific tiles were missed during a redesign carve-up. Distinct from `baked-payload-stale-after-merge` (producer didn't re-run) and from `cloud-run-results-bq-postsync` (write race) — this is the inverse: the producer has been correct for a long time, the CONSUMER never connected to it. Provides the "for each rendered number on every audit page, classify as payload-derived / hardcoded / mock-dat

Audit a whole live data-dashboard (or any multi-page user-facing product) for (1) numbers correctness against the source database and (2) language fit for stated audiences, in one synchronous ~30–45 minute round of parallel research subagents. Use when: (1) the user says "review this dashboard / site / app", "fact-check the numbers", "make sure the copy lands for X audience", or "do a whole-X audit"; (2) the product has 6+ user-facing pages backed by a queryable data source (BigQuery payload table, Postgres, read-replica, JSON cache, etc.); (3) the deliverable is a single written report the user can scan + decide what to fix; (4) the user has at least one written voice/persona doc (`PRODUCT.md`, brand guidelines, audience brief). Provides the cluster-split methodology (3–4 page-clusters by audience/purpose), the per-page diagnostic table schema (Element / Source / Claimed / Actual / Verdict), the subagent prompt template, the synthesis structure (TL;DR P0 table + per-page detail + cross-cutting themes), and t