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

retail-govern

Skill2 starsChanged 4 months agoApache-2.0View on GitHub

Run the Seshat BI governance checker and interpret its findings. Use when someone asks to check, validate, or gate Power BI / DAX / TMDL / PBIR / SQL work in the Seshat BI repo, when `seshat check` reports a rule violation, or when you need to know what a rule id (D8, C2, S2, G1, …) means and where to fix it. Invoke-and-interpret only: this skill does NOT build models, run pbi-cli, or auto-fix — it runs the checker and maps ids to fixes.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is 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.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. 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 155

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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-govern

Seshat BI's conventions are enforced by a static checker, seshat check. This skill teaches you to run it, read its findings, and map each rule id to the file and fix it points at. The authoritative catalog is the glossary's "Static check rules" section, which mirrors the checker's live rule registry; the rules manifest is the machine-readable inventory. (An older 23-rule governance-layer design doc is a historical record, NOT the current count -- do not cite it for the catalog.)

Scope boundary (read this first)

This skill is invoke-and-interpret only. It does not orchestrate a Power BI build, does not call pbi-cli or Power BI Desktop, and does not auto-fix or self-heal violations. Those are deferred D-layer work (spec §9). Here you run the checker, explain a finding, and tell the user (or the powerbi-analyst agent) the single place to change — then stop.

Run the checker

From the repo root:

seshat check

It parses the committed TMDL / PBIR / SQL / git text — no Power BI Desktop, no pbi-cli, no network — and exits non-zero if any error-severity finding exists. warning and info findings are printed but do not fail the build. Severity is layer-aware (see the recorded severity-posture inventory for the observed per-rule posture), so treat that record — not a hardcoded list here — as the source of truth for which ids warn vs error. (G2 emits an info "no PBIP project present" when the repo has no model yet.)

Read a finding

Each finding carries four fields: rule_id, severity (error / warning / info), a one-line message, and a locator. The locator is the most specific pointer available — path:line for an in-file violation, otherwise a file path, git ref, or commit SHA (the git-metadata rules have no natural line number). Start at the locator; the rule id tells you which fix below applies.

Rule id → meaning → where to fix

<!-- SESHAT-RULE-FIX-TABLE START -->

This table covers all 82 registered rules. It is GENERATED from rule-fixes.yaml -- edit that file and run python scripts/export_rule_fix_table.py, never this table.

RuleMeansWhere to fix
A1A route-registry target does not resolve and is not honestly marked plannedFix the path or mark the route planned in the route registry (routes.py)
A3Knowledge-map route ids ↔ routes.yaml ids are not in bijectionReconcile the two id sets (routes_coverage.py)
AD1A metric's additivity class is composed illegally with its lineage parents (or is absent/ambiguous)Set/fix the additivity class + lineage (additivity_consistency.py)
AL1A metric contract is blocked (+reasons) yet carries a SETTLED gold bindingEither resolve the assumption (unblock) or revert the binding to a placeholder (assumptions.py)
AL2Contracts on one gold table record contradictory decided ambiguity rulingsReconcile the conflicting rulings across the contracts (assumption_coherence.py)
AP1visual-qa and dashboard-qa list the same anti-patterns with matching numbering and namesalign the divergent anti-pattern name or number in visual-qa.md
AQ1A decision-question route dangles (Seeded but missing) or a Planned marker is staleFix the route target or its planned marker (answerability_reconciler.py)
B1Module-scope DB/network import in the static coreMake the DB/network import lazy (inside the function) (never_execute.py)
B3A live-surface module keeps a module-scope DB/network importMove the import lazy in the live-surface module (live_surface_boundary.py)
C1Connection-string literal in a sourceReplace the server/database arg with a parameter identifier (git_meta.py)
C2Committed secret / connection context (.env, DSN, DO cluster slug)Remove it, gitignore .env, rotate; move real values to .env (git_meta.py)
CB1a growth/comparison metric contract declares a comparison baseline and a primary date fieldadd the baseline (e.g. SPLY) and date field to the contract in the retail-kpi-knowledge contracts set
CT1declared text/background colour pairs meet the declared WCAG contrast flooradjust the text.* hex values or accessibility.min_text_contrast_ratio in *-design-tokens.yaml
CT2adjacent colors.data_colors entries clear the declared deltaE76 flooradjust the adjacent hex values or accessibility.min_adjacent_delta_e in *-design-tokens.yaml
CT3every pair of colors.data_colors entries clears the declared whole-set deltaE76 flooradjust the closest data_colors pair or accessibility.min_categorical_deltae in the tokens YAML
D1Measure not PascalCaseRename the measure in its .tmdl (dax.py)
D2Measure missing displayFolderAdd a displayFolder to the measure block (dax.py)
D3Duplicated measure logicReplace the inlined body with a [Name] reference (dax.py)
D4/ in a measureReplace with DIVIDE(num, den) (dax.py)
D5Implicit aggregation (WARNING)Set summarizeBy: none or annotate the exception (dax.py)
D6Bidirectional relationshipSet crossFilteringBehavior: singleDirection, or justify (dax.py)
D7Time-intelligence without a date-table markerMark a date table in the model (dax.py)
D8Model sources a non-gold schemaRepoint the partition/expression Schema=/FROM to gold (dax.py)
D9Hardcoded date literal in a measureAnchor on the date table instead of a literal (dax.py)
D10FILTER(ALL/ALLSELECTED/ALLEXCEPT(...)) full-table-scan anti-patternRewrite without the full-table scan (dax.py)
D11Measure missing a /// doc commentAdd a /// doc comment above the measure (dax.py)
DF1A parked-on dependency edge contradicts tracked-file evidenceFix the parked-on edge or the evidence (parked_on.py)
DL1Theme JSON is impure (carries more than styling defaults)Strip non-default content from the theme file (surface 3) (design_theme.py)
DL2A page background spec carries dynamic/data-bound content (not static structure)Remove the dynamic content from the background spec (surface 2) (design_background.py)
DL3a theme's background and dataColors stay faithful to the design tokens they compile fromcorrect the drifted background or dataColors[i] in the *.theme.json, or its source tokens YAML
DL4a filled design-review evidence record carries every required field, non-placeholderfill the missing or placeholder required field in that page's design-review-evidence.md
DL5a layout grid's column/row arithmetic closes against its canvas and marginscorrect the canvas/margin/grid numbers or the stale arithmetic_check booleans in design/grids/*.yaml
DL6a visual-spec that self-attests an anti-pattern also records a blocking reasonadd a real (non-placeholder) readiness.blocking_reasons entry to the visual-spec.yaml instance
DL7formatting-plan rows cite a real principle/token, use allowed statuses, and never self-ratifyfix the row's principle_cited/token_cited/status/ratified_by in formatting-plan.md
DL8theme sentiment colours stay faithful to a human-declared meta.sentiment_mapcorrect the drifted theme sentiment value, or the meta.sentiment_map entry in the tokens YAML
DL9a filled Report Intent record carries every required field, non-placeholderfill the missing field (audience, purpose, owner, evidence) in report-intent.yaml, creating the file if absent
DL10A page-section name is declared on one design surface but not the others, or a filled blueprint uses a section outside the declared vocabularyAlign the section keys across design/grids/16x9-grid.yaml, mobile-grid.yaml and templates/dashboard-page-blueprint.yaml, or fix the offending section: value in the filled blueprint (design_section_vocabulary.py)
DL11A design grid_ref/theme_ref names a file that does not exist, or a value_typography_ref dotted path resolves in no token filePoint the *_ref at a committed target, or set it to none if there deliberately is not one (design_ref_resolution.py)
DR1no tracked file sits under a known-bad path prefix and no known-stale prose phrase survivesdelete the file under the flagged prefix, or remove the phrase named in design-stale-phrases.yaml
DS1Decision Store records carry a valid id/status/decision_type/scope and leak no PII or secretsfix the malformed field or mask the PII/secret value in .seshat/semantic-decisions.yaml
DS2an approved decision's approval block is complete, named-human-shaped, and evidence-identifiedfill the missing approved_by/evidence_identity in .seshat/semantic-decisions.yaml
DS3a decision batch excludes critical types and records valid members, evidence, and confirmationfix the batch's members/excluded/evidence/confirmed_by in the decision store
DS4supersession references resolve and no two active decisions conflict on the same scopefix the dangling supersedes/superseded_by id, or resolve the scope conflict, in the decision store
DS5every approved decision carries non-empty evidence before a pass verdict can rest on itadd approval.evidence to the approved decision record in .seshat/semantic-decisions.yaml
G1.gitignore missing a required entryAdd **/.pbi/localSettings.json, **/.pbi/cache.abf, .env; never ignore definition/ (git_meta.py)
G2A definition/ artifact is untracked, or a cache file is trackedgit add the definition; stop tracking .pbi/localSettings.json / cache.abf (git_meta.py)
G3UTF-8 BOM in a committed text fileRe-save as UTF-8 without BOM (git_meta.py)
G4.gitattributes EOL entry missingAdd the glob→eol mapping (TMDL/PBIR/JSON=CRLF; SQL/MD/PY=LF) (git_meta.py)
G5Repo-relative path > 200 charsShorten the PBIP project/table name (git_meta.py)
G6Real host/value in a committed PBIP parameterReplace with a <placeholder>; real value comes from .env at refresh (g6.py)
HR1a dimension shared by two or more gold stars is declared conformed or distinct, and matchesdeclare the dimension's status in conformed-dimension-map.yaml, creating the file if absent
HR4when meta.freshness is present, its expected_cadence and max_staleness are well-formedfix or add meta.freshness.expected_cadence/max_staleness in the table's source-map.yaml
HR5an A10-flagged metric contract declares a valid time_additivity valueset time_additivity to fully/semi/non (never fully when A10-flagged) in the metric contract
HR6each RLS role contract's filter binds to a real column on a committed gold dimensionfix filter.gold_table/filter.column in mappings/<table>/roles/<file>.yaml to name a real dim_* column
HR7a non-full-rebuild gold load (append/upsert/partial delete) declares its reload/dedup keyadd ON CONFLICT, a -- reload-strategy: <key> header, or an entry in the warehouse load policy, creating the file if absent
HR8dim_date's generate_series uses a one-day step and non-reversed literal boundsuse INTERVAL '1 day' and correct the start/end order in the dim_date INSERT
HR9every column/measure reference in contracts, TMDL DAX, and dashboard bindings resolvesrename the orphaned reference to match a real TMDL column/measure, or fix the stale visual-contract-binding-map.md
HR11a metric's two or more bound columns share the same declared unit and currencyalign the mismatched columns[].unit/currency values in the table's source-map.yaml
HR12when present, source-data-contract.yaml has a filled schema, arrival cadence, restatement policyfill schema/arrival.cadence/restatement.policy in mappings/<table>/source-data-contract.yaml
HR13every columns[].gold_placement dim: prefix resolves to a dimension the map itself declaresfix the dim: prefix or dimension name in columns[].gold_placement in the source-map
KP1a metric contract opting into provenance fields keeps them well-formed and resolvablefix generic_kpi_ref/custom/decision_refs/source_evidence in the metric contract
KR1generic KPI registry entries are well-formed, unique, and free of client or physical-layer leakagefix the entry, or remove the leaked token, in the retail-kpi-knowledge registry
P1PBIP outside powerbi/, or SQL outside warehouse/Move the file to the right folder (git_meta.py)
P2Commit subject off-conventionReword to `^(feat\
PP1A required handoff-pack section is unfilled (incl. the publish-approval slot)Fill the section in the handoff pack (never self-grant the approval) (publish_pack.py)
R1Report model reference is absolute / byConnectionMake datasetReference.byPath.path relative in definition.pbir (pbir.py)
R2a PBIR report.json is valid JSON, keeps its $schema, resolves BaseTheme refs, defines no logicremove the business-logic key, or fix the BaseTheme path, in the report's definition/report.json
RS1A readiness-status file is internally inconsistent (status/evidence/blockers/approvals/current-stage disagree)Fix the offending field in mappings/<table>/readiness-status.yaml (readiness_status.py)
S1Non-snake_case SQL identifierRename the identifier in warehouse/**/*.sql (sql.py)
S2Stale raw/marts schema token (only in schema position)Rename the schema to bronze/silver/gold (sql.py)
S3View missing vw_ prefixRename the CREATE VIEW object (sql.py)
S4aMigration filename / numbering brokenRename to ^\d{4}_.+\.sql$; contiguous + unique (sql.py)
S4bBare CREATE/ALTER (layer-aware WARNING)Use a guarded form (IF NOT EXISTS, CREATE OR REPLACE VIEW) (sql.py)
S5Type discipline (RC7): money/qty not exact NUMERIC, or leading-zero id not TEXTFix the cast/type in the silver SQL (sql.py)
S6Gold dim missing its -1 unknown member (RC14)Add the -1 unknown member + FK COALESCE in the gold dim (sql_gold_members.py)
S7Date dim not a contiguous generate_series calendar (RC15)Build the date dim as a contiguous generated calendar (sql.py)
S8A marked date table carries a -1/NULL memberRemove the sentinel member from the date dim (sql_gold_members.py)
S9A junk filter targeting '' runs after nulling, so it is dead and the junk rows surviveMove the junk-row filter ahead of the ''->NULL conversion (sql.py)
SC1A prose status claim (planned/built) contradicts tracked-file evidenceCorrect the stale prose claim (status_claims.py)
SC2A prose "N rules" count claim disagrees with the authoritative countUpdate the count + the rule-count-claims.yaml anchor together (rule_count_claims.py)
SF1same-basename checklists shared across skills are declared shared/distinct and shared copies matchdeclare or fix the basename's shared/distinct status in shared-spine.yaml, creating the file if absent
SL1A coverage scorecard is malformed (bad status enum / unnamed blocker / a percentage)Fix the scorecard structure (scorecard.py)
<!-- SESHAT-RULE-FIX-TABLE END -->

What to do after interpreting

Report the failing ids, their locators, and the one fix each needs. Hand DAX/PBIP fixes to the powerbi-analyst agent; SQL fixes belong in warehouse/. Then stop — re-running seshat check to confirm green is the user's (or agent's) next call, not an automated loop this skill performs.

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.