retail-validate
Skill2 starsChanged 4 months agoApache-2.0View on GitHub
Run the LIVE data checks against a materialized retail table and interpret the findings. Use after silver + gold exist for a mapped table in the Seshat BI repo, when someone asks to validate or reconcile a table, or when a V-RC2 / V-RC15 / V-RC16 finding appears. Invoke-and-interpret only: this skill runs `retail validate` against a live Postgres DB and maps each finding id to its fix. It does NOT build models, write SQL, or auto-fix.
- Reads credentials
- Installs packages
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- approval-consoleSkill
- approval-evidence-packSkill
- business-knowledge-interviewSkill
- capabilitiesSkill
- consumer-data-dictionarySkill
- cross-table-lineageSkill
- dagster-orchestration-adapterSkill
- dashboard-designSkill
- dashboard-intelligenceSkill
- dbt-transformation-adapterSkill
- evidence-pack-generatorSkill
- first-hour-compassSkill
- friendly-pr-reviewerSkill
- grain-confidence-reviewerSkill
- kpi-contract-builderSkill
- pbi-mcp-write-adapterSkill
- pbip-workflowSkill
- pbip-xraySkill
- pbir-authoring-adapterSkill
- portfolio-watchSkill
- powerbi-dashboard-designSkill
- pr-readiness-reviewerSkill
- readiness-viewerSkill
- release-notes-generatorSkill
- report-intent-interviewSkill
- retail-build-warehouseSkill
- retail-control-roomSkill
- retail-discover-portfolioSkill
- retail-governSkill
- retail-initSkill
- retail-onboard-tableSkill
- retail-orchestrateSkill
- retail-scaffoldSkill
- retail-semantic-checkSkill
- run-next-readinessSkill
- seshat-studioSkill
- showcase-buildSkill
- source-mappingSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- bi-analyst-knowledgeSkill
- bi-bigdata-knowledgeSkill
- bi-dax-knowledgeSkill
- bi-python-knowledgeSkill
- bi-sql-knowledgeSkill
- retail-kpi-knowledgeSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 67
If no DSN is configured or the db extra is absent, retail validate does NOT traceback and does NOT pretend a run happened -- the live …
- Very specific: line 91
When a table is being driven end-to-end, the retail-orchestrate conductor skill sequences this verb with the others and runs the self-heal …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.yamlexists (the targets are derived from it -- table, PK, FK, measures). - The optional
dbextra is installed (pipx inject seshat-bi psycopg2-binary, orpip install "seshat-bi[db]") and a DSN is configured (DATABASE_URLor theANALYTICS_DB_*vars in the gitignored.env). Never commit a real DSN.
Run it
retail validate --source-map mappings/<table>/source-map.yamlThe 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. |
V-RC15 is the live complement of static S7: S7 proves dim_date is BUILT
from generate_series (the pattern); V-RC15 proves the calendar SPANS the data
(coverage). Both halves of RC15 must hold.
Deferred/live-boundary mode (no DSN or no db extra)
If no DSN is configured or the db extra is absent, retail validate does NOT
traceback and does NOT pretend a run happened -- the live boundary is
user-supplied by design (Principle VIII). Without --source-map it reports the
surface is built and how to target a table; without a DSN/driver it prints the
enable steps: pipx inject seshat-bi psycopg2-binary (or pip install "seshat-bi[db]"),
then set DATABASE_URL (or ANALYTICS_DB_*) in the gitignored .env. Report that
state; do not fake a pass.
What to do after interpreting
Report the failing ids, their locators, and the one fix each needs. Hand silver
fixes to warehouse/ SQL and gold/star fixes to the gold build; DAX/PBIP issues
go to the powerbi-analyst agent. Then STOP -- re-running retail validate to
confirm green is the user's next call, not a loop this skill performs.
See also
- The checks and their target sourcing both run inside
retail validate. - Principle VIII (static-first, live deferred) in the project constitution.
- The static sibling: the
retail-governskill. - The blank the run fills: the reconciliation-report template.
Orchestration
When a table is being driven end-to-end, the retail-orchestrate conductor skill
sequences this verb with the others and runs the self-heal loop against the gate
exit code. This skill stays single-purpose: it does its job and STOPS. The loop
(run gate -> classify findings -> auto-fix mechanical / HARD-STOP judgment calls ->
re-run) lives ONLY in retail-orchestrate, never here.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

