retail-semantic-check
Skill2 starsChanged 4 months agoApache-2.0View on GitHub
Compute the Semantic Model Ready (Stage 5) readiness verdict for a committed Power BI PBIP model in the Seshat BI repo. Use after Gold Ready is `pass`, when someone asks whether the semantic model is ready, to check that every measure binds to an approved metric contract, or before any dashboard/PBIP work. READ-ONLY and invoke-and-interpret only: it runs the existing `seshat check` gate, reads the committed TMDL and the filled metric-contract store (F009), and emits ONE status (not_started | blocked | warning | pass) with evidence + blockers, then STOPS. It NEVER edits TMDL, NEVER defines/approves a metric contract (that is F009), and NEVER calls the Power BI execution adapter (official Power BI MCP / connection; `pbi-cli` no longer preferred) -- that is F016.
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-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
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 70
NEVER treat the existence of templates/metric-contract.yaml (or kpi-pack.yaml) as "the store is present".
- Very specific: line 81
When the gate is green but no filled, approved contract backs the measures, the verdict is blocked, not pass, and the green run is cited as …
- Very specific: line 87
Read mappings/<table>/readiness-status.yaml.
- Distinctive: line 97
Run the same command CI runs:
- Distinctive: line 123
Read the FILLED metric-contract store (see "The store is FILLED contracts" above).
- Very specific: line 254
When a table is driven end-to-end, the retail-orchestrate conductor parks at the Phase-7 model seam and invokes this verb to compute the …
- Very specific: line 256
BEFORE any Power BI authoring.
≈ “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-semantic-check
seshat check proves the model is mechanically clean (PascalCase measures, display
folders, DIVIDE, single-direction relationships, a marked date table, gold-only
partitions, parameterized connection, no real host). This skill answers the larger
question that clean text alone cannot: is the semantic model GOVERNED -- does
every measure trace to an APPROVED metric contract, with the gold star already
live-validated underneath it? It computes the Stage-5 verdict and STOPS -- the live
sibling of retail-govern / retail-validate, one layer up: it governs the SEMANTIC
MODEL, not the SQL. It implements the procedure that
docs/readiness/semantic-model-ready.md specifies; it redefines nothing.
Scope boundary (read first)
Invoke-and-interpret only, and READ-ONLY.
- CHECKS the model. Reads the committed PBIP TMDL, reads the filled
metric-contract store, runs
seshat check, evaluates the contract-binding criterion, and emits one readiness verdict. All side-effect-free reads over committed text -- the same category asretail-governreading TMDL. - NEVER DEFINES contracts (F009). The metric-contract store (name, grain, formula
intent, owner, approval) is defined and owned by feature F009 (the
metric-contracttemplate + themetric-contract-storeguide). This skill is the CONSUMER: it reads contracts to test the binding; it never creates, edits, or approves one. - NEVER AUTHORS or EXECUTES the model (F016, deferred + gated). It writes no TMDL, adds/edits
no measure / relationship / date marker, opens no DB connection, and calls no
the Power BI execution adapter (official Power BI MCP / connection;
pbi-clino longer preferred) (constitution Principle II; roadmap hard rule #6 -- F016 is last and gated on THIS stage beingpass). It reads an EXISTING model and reports; a human edits Power BI Desktop and re-saves the PBIP to remediate.
Prerequisites
- The prior stage Gold Ready is
pass-- read it from the canonicalmappings/<table>/readiness-status.yaml(ADR 0004; shaped totemplates/readiness-status.yaml). This stage sits AFTER the live-validation hard gate (no gold to Power BI before validation, roadmap rule #4). If Gold Ready is notpass, the verdict isnot_startedand the skill STOPS. - The committed PBIP model exists under
powerbi/<Model>.SemanticModel/definition/. - The metric-contract store (F009) -- the FILLED, per-table contracts -- may or may
not exist. Its absence is not an error; it is the reason the verdict is
blocked(see the central property below).
The store is FILLED contracts, not the template (read this before binding)
F009 ships the TEMPLATE (templates/metric-contract.yaml) and the authoring guide
(docs/metrics/metric-contract-store.md). The TEMPLATE is the shape, NOT the store.
A binding target is a FILLED, owner-APPROVED contract at the canonical store location:
mappings/<table>/metrics/<MetricName>.yaml # filled per-table contracts (the store)
metrics/packs/<pack_name>.yaml # reusable KPI packs (group filled contracts)NEVER treat the existence of templates/metric-contract.yaml (or kpi-pack.yaml) as
"the store is present". The template existing is the F009 deliverable; it binds to
nothing. If no filled contract exists for a measure, that measure is unbound -> a
blocking_reason.
The central property: a green seshat check is NECESSARY, not SUFFICIENT
A clean mechanical gate (seshat check exit 0) does NOT make this stage pass.
pass ALSO requires the contract-binding criterion satisfied AND the metric owner's
approval recorded as evidence. Emitting pass on a green checker alone would be a
silent governance hole -- a perfectly-formed model whose measures bind to nothing.
When the gate is green but no filled, approved contract backs the measures, the
verdict is blocked, not pass, and the green run is cited as MECHANICAL-pass-only.
Run it -- the fixed 5-step evaluation order (do not reorder)
1. Ordering gate
Read mappings/<table>/readiness-status.yaml. If that file is absent or
unreadable, or gold_ready.status is anything other than pass, emit
not_started, record the blocking reason "prior stage Gold Ready is not proven
pass" (an absent readiness file means gold has not been live-validated -- e.g. the
deferred DB boundary), and STOP. Never check a model whose source gold is unproven
(Principle VIII). Reaching the binding criterion (step 4) requires clearing this gate
first; not_started here takes precedence over a blocked the later steps would
produce.
2. Mechanical gate
Run the same command CI runs:
seshat checkAny D1-D8 (TMDL/DAX), C1 (connection params), R1 (relative reference), or
G6 (no real host) finding is a distinct blocking_reason (cite the id + locator;
hand the fix to the retail-govern interpret table). Record the exit code as
evidence: exit 0 is MECHANICAL-pass-only, never a stage pass by itself.
3. Structural facts (interpret, do not re-implement)
The structural readiness the stage doc requires is already surfaced by step 2 -- interpret it, never re-code it:
| Fact | Surfaced by | Pass means |
| Relationships present + single-direction | D6 | star relationships exist; no bidirectional (or a justified, annotated exception) |
| A marked date table | D7 | the DATE_TABLE_MARKER annotation OR table-level dataCategory: Time + a key column is present |
| Measures PascalCase, in display folders | D1, D2 | every measure is PascalCase and carries a displayFolder |
| Gold-only partitions | D8 | every partition reads gold only |
A finding here is a step-2 blocking_reason; a clean pass here is recorded as part of
MECHANICAL-pass-only, still not a stage pass.
4. Contract-binding (the criterion this stage adds)
Read the FILLED metric-contract store (see "The store is FILLED contracts" above). For EACH PascalCase measure in the model:
- Matched + approved -> a measure that maps to a filled contract whose
readiness.statusispasswith owner-approval evidence (owner + date). Record the contract name + owner + date asevidence[]. - Unmatched (no filled contract for the measure) -> a distinct
blocking_reasonnaming the measure. NEVER auto-create the contract. - Matched but not approved (a filled contract exists but its status is not
pass/ no owner approval recorded) ->blocked("owner approval missing for<contract>"). Approval is a human action the skill cannot self-grant (Principle V). - Store absent (no
mappings/<table>/metrics/filled contracts at all) ->blocked("no filled, owner-approved metric contracts exist for this model's measures; the F009 template ships the shape but no per-table contract is authored"). - Ambiguous mapping (a measure name that does not map cleanly to a contract key) -> HARD-STOP and raise it for a human; never guess a match.
4b. Contract<->DAX drift (L3 -- the measure's LOGIC matches its contract)
Binding (step 4) proves a measure maps to an approved contract; it does NOT prove the
DAX LOGIC matches the contract's approved definition. A measure can bind to its
contract and still compute the WRONG number (the 50.37-vs-33.55 class: a denominator
over all transactions when the contract rules known-status only). seshat check (D-rules)
sees only form; nothing else sees a wrong denominator. L3 closes that gap.
For each measure whose contract carries an optional machine-readable definition
block, invoke the drift checker (a lazy module -- it reads YAML, so it is NOT part of
the seshat check core; mirrors validate_targets):
from retail.metric_drift import load_definition, check_measure_drift
defn = load_definition("mappings/<table>/metrics/<Measure>.yaml") # None if no block
verdict = check_measure_drift(<the measure's DAX body from the TMDL>, defn)
# verdict.status in {pass, drift, escalate, skip}Map the per-measure status to this stage:
- pass -> the DAX denominator filter-set matches the contract; record as
evidence[]. - drift -> a recognized mismatch (wrong/missing/extra denominator filter, wrong
column) ->
blockedwith the measure named ("DAX denominator drifts from the approved contract definition"). The fix is a human Desktop edit (re-save the PBIP) or a contract correction -- never self-applied here. - escalate -> the DAX uses a predicate spelling the checker does not recognize, is not a DIVIDE ratio, or is unparseable -> HARD-STOP and raise it for a human; NEVER guess pass or drift (the contract -- not the DAX shape -- is the sole arbiter; an unrecognized form is a human judgment call, Principle V).
- skip -> the contract has no
definitionblock yet -> no L3 finding (binding from step 4 still governs). Backward-compatible; contracts adopt the block incrementally.
The contract is the SOLE arbiter of the correct denominator direction. NEVER infer the
intended denominator from the DAX or the prose (an inference can be inverted -- it has
been). Only the structured definition decides; absent it, L3 stays silent (skip).
5. Verdict
Combine into EXACTLY ONE status, shaped to templates/readiness-status.yaml, with
evidence[] (committed files + the seshat check run) and blocking_reasons[]:
| Verdict | When |
not_started | step 1 failed (Gold Ready not pass) |
blocked | any step-2/3 finding, OR any unmatched/unapproved measure, OR store absent, OR an L3 drift (step 4b: DAX denominator contradicts the contract definition) |
warning | seshat check clean + binding satisfied, but a non-fatal recorded item (e.g. an accepted display-folder deviation), OR an L3 escalate left for human classification; never auto-promotes |
pass | steps 2-4(+4b) ALL clear AND every measure binds to an approved contract AND owner approval is recorded as evidence[] (any measure with a definition block is L3 pass or skip; none drift/escalate) |
A pass MUST carry evidence; never fabricate a confidence number (roadmap rule #9 --
the four explicit statuses + evidence + blockers are the only vocabulary). Then STOP.
Read-only / author-nothing contract
This skill writes no TMDL, edits no measure / relationship / date marker, opens no DB
connection, invokes no Power BI execution adapter (official Power BI MCP / connection;
pbi-cli no longer preferred), and modifies no file under
powerbi/. For every FIXABLE finding it REPORTS the human remediation step rather
than applying it:
| Fixable finding | Human remediation (the skill reports; never self-edits) |
D1 measure not PascalCase | rename the measure in Power BI Desktop, re-save the PBIP |
D2 measure missing displayFolder | set its display folder in Desktop, re-save the PBIP |
D4 / instead of DIVIDE() | rewrite the measure in Desktop, re-save the PBIP |
C1/R1/G6 connection / ref / host | repoint to parameters / a relative ref in Desktop, re-save |
| An unbound measure | author + owner-approve the metric contract under F009 (mappings/<table>/metrics/), not here |
Programmatic remediation (editing TMDL, marking a date table, adding a measure) is the
deferred, execution-only F016 Power BI adapter (official Power BI MCP / connection;
pbi-cli no longer preferred), gated on this stage being pass (Principle II;
hard rule #6).
Fail-loud judgment-stop table (HARD-STOP, never a silent default)
Each of these STOPS and is raised for a human -- the skill never picks a default:
| Situation | Why it stops |
| Filled metric-contract store absent | nothing to bind to; blocked, never a guessed pass |
| A measure name not cleanly mappable to a contract key | guessing a match would mis-govern; raise the ambiguous mapping |
warning-vs-blocked ambiguity | the analyst classifies the non-fatal item; do not auto-pick |
| Owner identity unclear for an approval | approval is a NAMED human action; the skill cannot self-grant it |
Grain semantics, PII publish-safety, business-rollup mappings, and product-identity are NOT decided by this skill -- they belong to the metric owner / F009 (Principle V).
What to do after interpreting
Report the one verdict, its evidence[], and each blocking_reason with the measure
or finding id it names and the one place to fix it (Desktop edit + re-save PBIP for
mechanical findings; author + owner-approve a contract under F009 for unbound
measures). Then STOP -- re-running the check after a human remediates is the user's
next call, not a loop this skill performs.
See also
- The stage authority (required artifacts, checks, statuses, approver):
docs/readiness/semantic-model-ready.md. - The spine:
docs/readiness/readiness-model.md,docs/readiness/readiness-pipeline.md. - The contracts it consumes (owned by F009):
templates/metric-contract.yaml,templates/kpi-pack.yaml,docs/metrics/metric-contract-store.md. - The mechanical gate it calls:
seshat check(D1-D8src/seshat/rules/dax.py,C1/R1src/seshat/rules/pbir.py,G6src/seshat/rules/g6.py); theretail-governskill for the id -> fix mapping. - The live sibling one layer down: the
retail-validateskill. - The model under check:
powerbi/Retailgold.SemanticModel/definition/. - The next stage (gated on this one passing):
docs/readiness/dashboard-ready.md, thedashboard-designskill (F011). - Roadmap hard rules #4 (gold validated first), #5 (no dashboard before contracts),
#6 (no pbi-cli before this stage passes), #9 (no fake confidence):
docs/roadmap/roadmap.md.
Orchestration
When a table is driven end-to-end, the retail-orchestrate conductor parks at the
Phase-7 model seam and invokes this verb to compute the Semantic Model Ready verdict
BEFORE any Power BI authoring. A pass is the gate that lets the next phase
(dashboard design, then official report authoring after its gate; live semantic
execution remains parked F016) proceed; anything else STOPS
the conductor with the blocking reasons. This skill stays single-purpose: it computes
one verdict and STOPS. The self-heal loop (run gate -> classify -> auto-fix mechanical
/ HARD-STOP judgment calls -> re-run) lives ONLY in retail-orchestrate, never here;
and contract approval is a human action no loop self-grants.
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.

