SuperAPI AI Directory

review-pbi-diff

General & other

View repository

Updated 10-16 05:44

About this skill

Review Power BI diff

Turn a large, unreadable PBIP diff (hash-named visual.json files, TMDL model files) into a single review artifact: an executive summary of what was built, page wireframes showing what changed where, spec-checked measures with full DAX, and a ranked red-flags list. The reviewer is a Power BI expert, so show raw DAX and exact bindings.

Input: an optional git ref range as the argument (A...B, A..B, or a single base ref meaning "vs working tree"). Default: main...HEAD. The user may also name pages to treat as scratch, beyond the automatic rule below.

Scope: review and report. Findings go in the artifact, not into edits to the PBIP files, the DAX, or an issue tracker.

Step 1: extract the change model (deterministic)

Run the bundled extractor, outputting to the scratchpad:

python3 <skill-dir>/scripts/extract_changes.py "<range>" \
  --out <scratchpad>/pbi-review --repo <repo-root>

<skill-dir> is this skill's directory. It produces:

  • <out>/change_model.json: the structured change model. Everything below works from this file, not from the raw git diff.
  • <out>/objects/<repo-path>.before|.after: raw before/after of every changed file, for drill-down when something in the model looks suspicious.

Change-model shape: reports.<name>.pages.<id> has display_name, status (added / modified / visuals-changed / deleted), width/height, visibility (present when not default-visible), scratch (see below), page filters, and visuals.<id>. This covers every visual on each touched page (including unchanged ones, so wireframes are complete), with visual_type, title, abs_x/abs_y/width/height/z, status, fields (role to bound fields), filters, and for modified visuals changed_sections plus *_before values. Each page also carries overlaps: pairs {a, b, pct_of_smaller} of visual ids whose boxes intersect by more than 15% of the smaller visual's area (hidden, deleted and group containers excluded). models.<name> has per-table measures_added/modified/deleted (with full DAX, dax_before/dax_after for modified), same for columns and calculation_items, plus relationships and functions diffs. commits and authors identify whose work this is. Calculation-group internals and partition/refresh-policy changes are not member-diffed. The change model flags the table with a note; drill into objects/ for those.

If change_model.json is large, query it with python one-liners rather than reading it whole; read pages/tables one at a time.

Scratch pages

Pages marked scratch: true (Power BI default names, Page N), plus any pages the user named at invocation, are developer scratch work. Review the model in full, but curated pages only: scratch pages get no wireframe, no visual tables, and no red-flag checks except #11. References from their visuals (checks 3-4) aren't findings; they go in the exclusion line. They surface in the artifact exactly twice: the exclusion line (see references/artifact.md) and, when visible, check #11.

Step 2: analyze

Spec check (every added/modified measure)

For each measure in measures_added / measures_modified, look for a matching definition in the repo's metric-definition docs. Try docs/metric-definitions/ first, else search the repo for definition-style docs, else ask the user where definitions live (match by name, then by concept). Verdicts, each rendered as a badge in the artifact:

  • ✅ Matches definition. DAX implements the documented logic (check the numerator/denominator, grain, filter context, exclusions, and business-hours flags, not just the name).
  • ⚠️ Deviates. State exactly how the DAX differs from the definition.
  • ❓ No definition found. This is itself a useful finding; list these so docs can catch up. If the repo has no metric-definition docs at all, say so once and mark every measure ❓ without repeating it per measure.

Done when every added/modified measure carries a verdict. For a large measure set, delegate batches to parallel subagents (each gets its batch plus the definitions docs) and merge their verdicts into one list.

If the repo documents requirements (e.g. docs/requirements/), also map the overall work against them: which requirements does this branch address, and what claimed scope is missing.

Red-flag checks

Run every check below. A candidate becomes a finding only with evidence from the change model or the objects/…before|.after files, and is discarded only when that evidence disproves it. Rank each finding 🔴 wrong results / broken, 🟡 should fix before merge, 🔵 minor/hygiene, and cite what you checked. One you can neither confirm nor disprove ships as 🔵 stating what you checked and what is still unknown. A check with no findings is reported as confirmed clean.

  1. Bare / division in new/changed DAX where the denominator can be zero/blank (DIVIDE is the safe idiom).
  2. Missing formatString on added measures that return numbers.
  3. Deleted or renamed measures still referenced. Grep the repo at head for each deleted measure name (visuals reference them as <Table>.<Name> in queryRef, other measures as [<Name>]). A rename shows up as one added + one deleted measure; check the deleted name. Flag equally any visual binding to a measure that doesn't exist in the model at head (e.g. a missing name prefix).
  4. Modified measure ripple. For measures whose DAX changed, grep which other measures/visuals reference them and note affected downstream logic.
  5. USERELATIONSHIP targets. Confirm the named relationship exists (check relationships in the change model and definition/relationships.tmdl at head) and is inactive as expected.
  6. Visuals bound to unrelated tables. Fields from two fact tables with no relationship path on the same visual.
  7. Placeholder names. Visuals left untitled where siblings are titled.
  8. Hidden filters that change data. Visual/page filters with hidden_in_view: true (field emitted only when true).
  9. Overlapping data visuals on the same page: review each pair in the page's overlaps list (the extractor reports pairs covering more than 15% of the smaller visual's area) and flag those where both are data visuals rather than shapes/textboxes layered as backgrounds.
  10. Hardcoded literals in DAX (magic dates, hardcoded brand/region values) and, when the repo documents naming/DAX standards (e.g. under docs/standards/), convention violations against them.
  11. Visible scratch pages. A scratch page without visibility: HiddenInViewMode ships to end users: 🟡 hide (or delete) before publishing. Hidden scratch pages are tolerated.

Step 3: build the artifact

Follow references/artifact.md for the structure, wireframe rules, and check markers. Length follows substance: prefer wireframes and tables over prose, skip filler, and never restate a table in prose beneath it. Load the artifact-design skill if available, write one self-contained HTML file to the scratchpad, then prove it against the change model, passing only user-named scratch pages (REPORT/PAGE if ambiguous):

python3 <skill-dir>/scripts/check_artifact.py <out>/change_model.json <file.html> [--scratch <page>]...

Fix every problem it lists and rerun until it prints PASS. Then publish with the Artifact tool (icon chart, stable title PBI Review: <branch or range>), or else give the user the HTML path. Close out with the outcome (URL or path, the check's 🔴/🟡/🔵 counts and excluded pages), then detail.