agentleFS
KemetraKemetra/Seshat-BI/.claude/skills/retail-validate/SKILL.md

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

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
  1. Very specific:

    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 …

    line 67
  2. Very specific:

    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 …

    line 91

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

FindingMeansFix at
V-RC2PK 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-RC15The 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-govern skill.
  • 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.