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

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.

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

    NEVER treat the existence of templates/metric-contract.yaml (or kpi-pack.yaml) as "the store is present".

    line 70
  2. Very specific:

    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 …

    line 81
  3. Very specific:

    Read mappings/<table>/readiness-status.yaml.

    line 87
  4. Distinctive:

    Run the same command CI runs:

    line 97
  5. Distinctive:

    Read the FILLED metric-contract store (see "The store is FILLED contracts" above).

    line 123
  6. Very specific:

    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 …

    line 254
  7. Very specific:

    BEFORE any Power BI authoring.

    line 256

≈ “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-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 as retail-govern reading TMDL.
  • NEVER DEFINES contracts (F009). The metric-contract store (name, grain, formula intent, owner, approval) is defined and owned by feature F009 (the metric-contract template + the metric-contract-store guide). 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-cli no longer preferred) (constitution Principle II; roadmap hard rule #6 -- F016 is last and gated on THIS stage being pass). 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 canonical mappings/<table>/readiness-status.yaml (ADR 0004; shaped to templates/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 not pass, the verdict is not_started and 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 check

Any 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:

FactSurfaced byPass means
Relationships present + single-directionD6star relationships exist; no bidirectional (or a justified, annotated exception)
A marked date tableD7the DATE_TABLE_MARKER annotation OR table-level dataCategory: Time + a key column is present
Measures PascalCase, in display foldersD1, D2every measure is PascalCase and carries a displayFolder
Gold-only partitionsD8every 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.status is pass with owner-approval evidence (owner + date). Record the contract name + owner + date as evidence[].
  • Unmatched (no filled contract for the measure) -> a distinct blocking_reason naming 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) -> blocked with 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 definition block 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[]:

VerdictWhen
not_startedstep 1 failed (Gold Ready not pass)
blockedany step-2/3 finding, OR any unmatched/unapproved measure, OR store absent, OR an L3 drift (step 4b: DAX denominator contradicts the contract definition)
warningseshat 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
passsteps 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 findingHuman remediation (the skill reports; never self-edits)
D1 measure not PascalCaserename the measure in Power BI Desktop, re-save the PBIP
D2 measure missing displayFolderset 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 / hostrepoint to parameters / a relative ref in Desktop, re-save
An unbound measureauthor + 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:

SituationWhy it stops
Filled metric-contract store absentnothing to bind to; blocked, never a guessed pass
A measure name not cleanly mappable to a contract keyguessing a match would mis-govern; raise the ambiguous mapping
warning-vs-blocked ambiguitythe analyst classifies the non-fatal item; do not auto-pick
Owner identity unclear for an approvalapproval 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-D8 src/seshat/rules/dax.py, C1/R1 src/seshat/rules/pbir.py, G6 src/seshat/rules/g6.py); the retail-govern skill for the id -> fix mapping.
  • The live sibling one layer down: the retail-validate skill.
  • The model under check: powerbi/Retailgold.SemanticModel/definition/.
  • The next stage (gated on this one passing): docs/readiness/dashboard-ready.md, the dashboard-design skill (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.

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.