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
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-initSkill
- retail-onboard-tableSkill
- retail-orchestrateSkill
- retail-scaffoldSkill
- retail-semantic-checkSkill
- retail-validateSkill
- 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
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
- Very specific: line 155
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 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.
Files
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 checkIt 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.
| Rule | Means | Where to fix |
A1 | A route-registry target does not resolve and is not honestly marked planned | Fix the path or mark the route planned in the route registry (routes.py) |
A3 | Knowledge-map route ids ↔ routes.yaml ids are not in bijection | Reconcile the two id sets (routes_coverage.py) |
AD1 | A metric's additivity class is composed illegally with its lineage parents (or is absent/ambiguous) | Set/fix the additivity class + lineage (additivity_consistency.py) |
AL1 | A metric contract is blocked (+reasons) yet carries a SETTLED gold binding | Either resolve the assumption (unblock) or revert the binding to a placeholder (assumptions.py) |
AL2 | Contracts on one gold table record contradictory decided ambiguity rulings | Reconcile the conflicting rulings across the contracts (assumption_coherence.py) |
AP1 | visual-qa and dashboard-qa list the same anti-patterns with matching numbering and names | align the divergent anti-pattern name or number in visual-qa.md |
AQ1 | A decision-question route dangles (Seeded but missing) or a Planned marker is stale | Fix the route target or its planned marker (answerability_reconciler.py) |
B1 | Module-scope DB/network import in the static core | Make the DB/network import lazy (inside the function) (never_execute.py) |
B3 | A live-surface module keeps a module-scope DB/network import | Move the import lazy in the live-surface module (live_surface_boundary.py) |
C1 | Connection-string literal in a source | Replace the server/database arg with a parameter identifier (git_meta.py) |
C2 | Committed secret / connection context (.env, DSN, DO cluster slug) | Remove it, gitignore .env, rotate; move real values to .env (git_meta.py) |
CB1 | a growth/comparison metric contract declares a comparison baseline and a primary date field | add the baseline (e.g. SPLY) and date field to the contract in the retail-kpi-knowledge contracts set |
CT1 | declared text/background colour pairs meet the declared WCAG contrast floor | adjust the text.* hex values or accessibility.min_text_contrast_ratio in *-design-tokens.yaml |
CT2 | adjacent colors.data_colors entries clear the declared deltaE76 floor | adjust the adjacent hex values or accessibility.min_adjacent_delta_e in *-design-tokens.yaml |
CT3 | every pair of colors.data_colors entries clears the declared whole-set deltaE76 floor | adjust the closest data_colors pair or accessibility.min_categorical_deltae in the tokens YAML |
D1 | Measure not PascalCase | Rename the measure in its .tmdl (dax.py) |
D2 | Measure missing displayFolder | Add a displayFolder to the measure block (dax.py) |
D3 | Duplicated measure logic | Replace the inlined body with a [Name] reference (dax.py) |
D4 | / in a measure | Replace with DIVIDE(num, den) (dax.py) |
D5 | Implicit aggregation (WARNING) | Set summarizeBy: none or annotate the exception (dax.py) |
D6 | Bidirectional relationship | Set crossFilteringBehavior: singleDirection, or justify (dax.py) |
D7 | Time-intelligence without a date-table marker | Mark a date table in the model (dax.py) |
D8 | Model sources a non-gold schema | Repoint the partition/expression Schema=/FROM to gold (dax.py) |
D9 | Hardcoded date literal in a measure | Anchor on the date table instead of a literal (dax.py) |
D10 | FILTER(ALL/ALLSELECTED/ALLEXCEPT(...)) full-table-scan anti-pattern | Rewrite without the full-table scan (dax.py) |
D11 | Measure missing a /// doc comment | Add a /// doc comment above the measure (dax.py) |
DF1 | A parked-on dependency edge contradicts tracked-file evidence | Fix the parked-on edge or the evidence (parked_on.py) |
DL1 | Theme JSON is impure (carries more than styling defaults) | Strip non-default content from the theme file (surface 3) (design_theme.py) |
DL2 | A page background spec carries dynamic/data-bound content (not static structure) | Remove the dynamic content from the background spec (surface 2) (design_background.py) |
DL3 | a theme's background and dataColors stay faithful to the design tokens they compile from | correct the drifted background or dataColors[i] in the *.theme.json, or its source tokens YAML |
DL4 | a filled design-review evidence record carries every required field, non-placeholder | fill the missing or placeholder required field in that page's design-review-evidence.md |
DL5 | a layout grid's column/row arithmetic closes against its canvas and margins | correct the canvas/margin/grid numbers or the stale arithmetic_check booleans in design/grids/*.yaml |
DL6 | a visual-spec that self-attests an anti-pattern also records a blocking reason | add a real (non-placeholder) readiness.blocking_reasons entry to the visual-spec.yaml instance |
DL7 | formatting-plan rows cite a real principle/token, use allowed statuses, and never self-ratify | fix the row's principle_cited/token_cited/status/ratified_by in formatting-plan.md |
DL8 | theme sentiment colours stay faithful to a human-declared meta.sentiment_map | correct the drifted theme sentiment value, or the meta.sentiment_map entry in the tokens YAML |
DL9 | a filled Report Intent record carries every required field, non-placeholder | fill the missing field (audience, purpose, owner, evidence) in report-intent.yaml, creating the file if absent |
DL10 | A page-section name is declared on one design surface but not the others, or a filled blueprint uses a section outside the declared vocabulary | Align 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) |
DL11 | A design grid_ref/theme_ref names a file that does not exist, or a value_typography_ref dotted path resolves in no token file | Point the *_ref at a committed target, or set it to none if there deliberately is not one (design_ref_resolution.py) |
DR1 | no tracked file sits under a known-bad path prefix and no known-stale prose phrase survives | delete the file under the flagged prefix, or remove the phrase named in design-stale-phrases.yaml |
DS1 | Decision Store records carry a valid id/status/decision_type/scope and leak no PII or secrets | fix the malformed field or mask the PII/secret value in .seshat/semantic-decisions.yaml |
DS2 | an approved decision's approval block is complete, named-human-shaped, and evidence-identified | fill the missing approved_by/evidence_identity in .seshat/semantic-decisions.yaml |
DS3 | a decision batch excludes critical types and records valid members, evidence, and confirmation | fix the batch's members/excluded/evidence/confirmed_by in the decision store |
DS4 | supersession references resolve and no two active decisions conflict on the same scope | fix the dangling supersedes/superseded_by id, or resolve the scope conflict, in the decision store |
DS5 | every approved decision carries non-empty evidence before a pass verdict can rest on it | add approval.evidence to the approved decision record in .seshat/semantic-decisions.yaml |
G1 | .gitignore missing a required entry | Add **/.pbi/localSettings.json, **/.pbi/cache.abf, .env; never ignore definition/ (git_meta.py) |
G2 | A definition/ artifact is untracked, or a cache file is tracked | git add the definition; stop tracking .pbi/localSettings.json / cache.abf (git_meta.py) |
G3 | UTF-8 BOM in a committed text file | Re-save as UTF-8 without BOM (git_meta.py) |
G4 | .gitattributes EOL entry missing | Add the glob→eol mapping (TMDL/PBIR/JSON=CRLF; SQL/MD/PY=LF) (git_meta.py) |
G5 | Repo-relative path > 200 chars | Shorten the PBIP project/table name (git_meta.py) |
G6 | Real host/value in a committed PBIP parameter | Replace with a <placeholder>; real value comes from .env at refresh (g6.py) |
HR1 | a dimension shared by two or more gold stars is declared conformed or distinct, and matches | declare the dimension's status in conformed-dimension-map.yaml, creating the file if absent |
HR4 | when meta.freshness is present, its expected_cadence and max_staleness are well-formed | fix or add meta.freshness.expected_cadence/max_staleness in the table's source-map.yaml |
HR5 | an A10-flagged metric contract declares a valid time_additivity value | set time_additivity to fully/semi/non (never fully when A10-flagged) in the metric contract |
HR6 | each RLS role contract's filter binds to a real column on a committed gold dimension | fix filter.gold_table/filter.column in mappings/<table>/roles/<file>.yaml to name a real dim_* column |
HR7 | a non-full-rebuild gold load (append/upsert/partial delete) declares its reload/dedup key | add ON CONFLICT, a -- reload-strategy: <key> header, or an entry in the warehouse load policy, creating the file if absent |
HR8 | dim_date's generate_series uses a one-day step and non-reversed literal bounds | use INTERVAL '1 day' and correct the start/end order in the dim_date INSERT |
HR9 | every column/measure reference in contracts, TMDL DAX, and dashboard bindings resolves | rename the orphaned reference to match a real TMDL column/measure, or fix the stale visual-contract-binding-map.md |
HR11 | a metric's two or more bound columns share the same declared unit and currency | align the mismatched columns[].unit/currency values in the table's source-map.yaml |
HR12 | when present, source-data-contract.yaml has a filled schema, arrival cadence, restatement policy | fill schema/arrival.cadence/restatement.policy in mappings/<table>/source-data-contract.yaml |
HR13 | every columns[].gold_placement dim: prefix resolves to a dimension the map itself declares | fix the dim: prefix or dimension name in columns[].gold_placement in the source-map |
KP1 | a metric contract opting into provenance fields keeps them well-formed and resolvable | fix generic_kpi_ref/custom/decision_refs/source_evidence in the metric contract |
KR1 | generic KPI registry entries are well-formed, unique, and free of client or physical-layer leakage | fix the entry, or remove the leaked token, in the retail-kpi-knowledge registry |
P1 | PBIP outside powerbi/, or SQL outside warehouse/ | Move the file to the right folder (git_meta.py) |
P2 | Commit subject off-convention | Reword to `^(feat\ |
PP1 | A 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) |
R1 | Report model reference is absolute / byConnection | Make datasetReference.byPath.path relative in definition.pbir (pbir.py) |
R2 | a PBIR report.json is valid JSON, keeps its $schema, resolves BaseTheme refs, defines no logic | remove the business-logic key, or fix the BaseTheme path, in the report's definition/report.json |
RS1 | A 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) |
S1 | Non-snake_case SQL identifier | Rename the identifier in warehouse/**/*.sql (sql.py) |
S2 | Stale raw/marts schema token (only in schema position) | Rename the schema to bronze/silver/gold (sql.py) |
S3 | View missing vw_ prefix | Rename the CREATE VIEW object (sql.py) |
S4a | Migration filename / numbering broken | Rename to ^\d{4}_.+\.sql$; contiguous + unique (sql.py) |
S4b | Bare CREATE/ALTER (layer-aware WARNING) | Use a guarded form (IF NOT EXISTS, CREATE OR REPLACE VIEW) (sql.py) |
S5 | Type discipline (RC7): money/qty not exact NUMERIC, or leading-zero id not TEXT | Fix the cast/type in the silver SQL (sql.py) |
S6 | Gold dim missing its -1 unknown member (RC14) | Add the -1 unknown member + FK COALESCE in the gold dim (sql_gold_members.py) |
S7 | Date dim not a contiguous generate_series calendar (RC15) | Build the date dim as a contiguous generated calendar (sql.py) |
S8 | A marked date table carries a -1/NULL member | Remove the sentinel member from the date dim (sql_gold_members.py) |
S9 | A junk filter targeting '' runs after nulling, so it is dead and the junk rows survive | Move the junk-row filter ahead of the ''->NULL conversion (sql.py) |
SC1 | A prose status claim (planned/built) contradicts tracked-file evidence | Correct the stale prose claim (status_claims.py) |
SC2 | A prose "N rules" count claim disagrees with the authoritative count | Update the count + the rule-count-claims.yaml anchor together (rule_count_claims.py) |
SF1 | same-basename checklists shared across skills are declared shared/distinct and shared copies match | declare or fix the basename's shared/distinct status in shared-spine.yaml, creating the file if absent |
SL1 | A 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.
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.

