Seshat-BI: Skill for Claude Code

retail-validate

seshat check proves everything provable from committed text. retail validate proves the four things only a running database can show, on the MATERIALIZED rows (constitution Principle VIII). This skill runs it and maps each finding to the one place to fix it -- the live sibling of retail-govern.

Scope boundary (read first)

Invoke-and-interpret only. This skill runs the live checks and explains findings; it does NOT write or fix silver/gold SQL, does NOT call pbi-cli, and does NOT auto-loop. The live run needs a DB and is the user's call; you report and stop.

Prerequisites

• silver + gold are materialized for the table.
• A reviewed mappings/<table>/source-map.yaml exists (the targets are derived from it -- table, PK, FK, measures).
• The optional db extra is installed (pipx inject seshat-bi psycopg2-binary, or pip install "seshat-bi[db]") and a DSN is configured (DATABASE_URL or the ANALYTICS_DB_* vars in the gitignored .env). Never commit a real DSN.

Run it

retail validate --source-map mappings/<table>/source-map.yaml

The connection is host-agnostic (any Postgres: local / remote / DigitalOcean / other) and READ-ONLY (the session is opened read-only; the checks only SELECT). Exit is non-zero iff any check finds a defect.

Read a finding

Each is a Finding(rule_id, severity, message, locator). Live findings are ERROR (proven defects -- a real PK duplicate, a real orphan, a real penny mismatch), unlike the static rules' WARNING (suspect patterns). Start at the locator; the id tells you which fix applies.

Finding id -> meaning -> where to fix

Finding	Means	Fix at
V-RC2	PK not unique, or has a NULL, on the materialized silver table (RC2).	Fix the grain or dedup in the silver SQL; re-verify the map's PK on the TRANSFORMED output (landed uniqueness is not enough).
V-RC15	The date dimension does not span every fact date -- the calendar has gaps (RC15 coverage; the live half of static rule S7).	Widen the generate_series bounds in the date-dim build to cover min..max fact date.
V-RC16 (orphan)	A fact FK points outside its dimension (RC16; 0 orphans required).	Fix the FK COALESCE to the -1 unknown member, or fix the dimension load so the key exists.
V-RC16 (reconcile)	A measure total differs between silver and gold (RC16; must reconcile to the penny).	Fix the gold aggregation (a join fan-out or filter is dropping/duplicating rows) until silver and gold totals match exactly.