@luquimbo/bi-superpowers 5.0.0 → 5.0.1

package/src/content/skills/bi-report/references/close-write-open-pattern.md

@@ -1,80 +0,0 @@
-# The close-write-open pattern
-
-This is the most important pattern in the skill. Get it wrong and **none of the visuals you generate will render** — not because the JSON is invalid, but because Power BI Desktop refuses to re-read the files while it's open.
-
-## The core fact
-
-Power BI Desktop reads `visual.json`, `page.json`, and the rest of the PBIR tree **once**, when the `.pbip` is first loaded by the app process. After that, it holds the report in memory and ignores file changes on disk. This is **not** a bug we can work around with the public CLI — it's Desktop's current design.
-
-Kurt Buhler documents this explicitly in the `power-bi-agentic-development/plugins/pbip/skills/pbip/SKILL.md`:
-
-> **"PBI Desktop does not detect external changes. Close and reopen PBI Desktop after editing files externally."**
-
-The subtle part: **"close"** here means kill the `PBIDesktop.exe` process, not `File → Close` inside the app. A file-level close keeps the app process alive with its cache intact. When the user then opens the file again via "Recent files" or drag, Desktop uses its cached state and silently ignores any new visual folders on disk.
-
-## The correct sequence
-
-```
-1. User has Power BI Desktop open with the .pbip
-2. Skill asks user to save any pending Desktop-side work
-3. Skill kills PBIDesktop.exe (process-level)
-4. Skill writes visuals via pbi CLI (while Desktop is dead)
-5. Skill relaunches the .pbip via Start-Process
-6. A new Desktop process boots, reads files from disk fresh, renders everything
-```
-
-## Commands
-
-### Kill Desktop
-
-Use `cmd //c` in Git Bash to avoid the MSYS path-mangling bug that eats the `/IM` flag:
-
-```bash
-cmd //c "taskkill /IM PBIDesktop.exe /F"
-cmd //c "taskkill /IM msmdsrv.exe /F"   # Analysis Services — Desktop usually kills this itself but belt-and-braces
-```
-
-Verify termination:
-
-```bash
-tasklist | grep -iE "PBIDesktop|msmdsrv"   # should return no lines
-```
-
-### Relaunch the .pbip
-
-PowerShell's `Start-Process` runs the shell-open association, which for `.pbip` files launches Power BI Desktop:
-
-```bash
-powershell -Command "Start-Process -FilePath './pbip-files/MyProject.pbip'"
-```
-
-Desktop takes ~10-20 seconds to fully load the model and render the visuals. The user sees "loading" screens during that window.
-
-## What does NOT work (confirmed failures)
-
-- **`File → Close` + `File → Open Recent`** — keeps the process alive, cache persists, new visuals ignored
-- **`Ctrl+Shift+F5` (CLI `pbi report reload`)** — only triggers a data refresh, not a structural re-scan of disk
-- **`File → Save` after external writes** — Desktop saves its in-memory state back to disk, which may OVERWRITE the externally-written files with the old state. Dangerous.
-- **Reopening the file by path while the same Desktop process is running** — same process, same cache, same problem
-
-## Why `pbi report reload` exists if it doesn't solve this
-
-The reload command is useful for smaller cases: refreshing data, picking up a theme change, re-running a single-visual query. It's not meant to discover newly-added visual folders, and the CLI docs don't claim it does.
-
-## Gotchas
-
-- **User has unsaved work in Desktop**: killing the process without prompting loses that work. Always ask before taskkill. If they have changes, tell them to save first.
-- **msmdsrv.exe lingering**: Desktop usually cleans it up, but occasionally it stays. Kill it separately to free port 53xxx that the CLI uses for `pbi connect`.
-- **Start-Process can't find the .pbip**: the path needs to be relative to CWD or absolute. If you're in `bi-superpowers/` but the .pbip is under `examples/smoke-test/pbip-files/`, use the full relative path.
-- **User has multiple Desktops open**: `taskkill /IM PBIDesktop.exe /F` kills ALL of them. If the user works with multiple .pbip files simultaneously, warn them or narrow the kill to the specific PID (via `tasklist` first).
-- **Virus scanner delays**: some AV tools lock the .pbip briefly after relaunch, causing a ~5-10s delay before Desktop shows anything. Normal, just wait.
-
-## How this maps to the skill phases
-
-| Phase | What to do |
-|---|---|
-| PHASE 2 end | `pbi disconnect` before kill (socket cleanup) |
-| PHASE 3 | Kill Desktop (with user confirmation) |
-| PHASE 4 | Write via CLI (Desktop is dead — no sync conflicts) |
-| PHASE 5 | Relaunch via `Start-Process` |
-| Post-PHASE 5 | User visually confirms render |

package/src/content/skills/bi-report/references/layouts/finance.md

@@ -1,65 +0,0 @@
-# Finance layout (3 pages)
-
-Assumed fact table: `GeneralLedger` (or similar). Common dims: `Date`, `Account`, `CostCenter`, `Scenario`. Key measures expected: total revenue, total expense, net profit, margin, variance vs budget.
-
-Roles used below (to be resolved via the MCP):
-- `primary-kpi` — top-line KPI (e.g., Net Revenue)
-- `secondary-kpi-1/2/3` — 3 supporting KPIs (e.g., Gross Margin, EBITDA, Expense)
-- `variance-measure` — signed delta (e.g., Variance vs Budget)
-- `time-dim-column` — date column from Date dim
-- `account-dim-column` — Account dim name or category
-- `costcenter-dim-column` — CostCenter dim
-
----
-
-## Page 1: `ResumenEjecutivo` / "Resumen Ejecutivo"
-
-**Grid (1280×720):**
-
-| Visual | Primitive | Position (x, y, w, h) | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | static text "Resumen Ejecutivo" |
-| KPI 1 | card | 16, 80, 280, 120 | `primary-kpi` |
-| KPI 2 | card | 312, 80, 280, 120 | `secondary-kpi-1` |
-| KPI 3 | card | 608, 80, 280, 120 | `secondary-kpi-2` |
-| KPI 4 (variance, signed) | card + conditional color | 904, 80, 280, 120 | `variance-measure` |
-| Revenue over time | line_chart | 16, 216, 816, 320 | `primary-kpi` × `time-dim-column` |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 216, 336, 80 | `'Date'[Year]` |
-| Scenario slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 312, 336, 80 | `Scenario[Scenario]` |
-
-**Design notes:**
-- Variance KPI: green/red conditional coloring is design intent only. Render as a plain card with theme/default colors unless a tested PBIR formatting implementation is available.
-- Year slicer default: current year (single-select).
-
----
-
-## Page 2: `AnalisisCuentas` / "Análisis por cuenta"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Análisis por cuenta" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| CostCenter slicer | slicer (manual JSON — see `references/slicer.md`) | 312, 80, 280, 80 | `CostCenter[Name]` |
-| Top accounts bar | bar_chart (horizontal) | 16, 176, 608, 480 | `primary-kpi` by `account-dim-column`, TopN 15 |
-| Detail matrix | matrix | 640, 176, 544, 480 | rows: `account-dim-column`, cols: `'Date'[Year]`, values: `primary-kpi` |
-
-**Design notes:**
-- Matrix uses gradient conditional formatting on the value column.
-- Bar chart sorts descending by `primary-kpi`.
-
----
-
-## Page 3: `DetalleVariance` / "Detalle de variance"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Detalle de variance vs budget" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| Scenario slicer | slicer (manual JSON — see `references/slicer.md`) | 312, 80, 280, 80 | `Scenario[Scenario]` |
-| Variance by costcenter | bar_chart | 16, 176, 608, 320 | `variance-measure` by `costcenter-dim-column`, bars colored by sign (diverging) |
-| Variance trend | line_chart | 640, 176, 544, 320 | `variance-measure` by `time-dim-column` |
-| Account × Month matrix | matrix | 16, 512, 1168, 144 | rows: `account-dim-column`, cols: `'Date'[Month]`, values: `variance-measure` with diverging gradient |
-
-**Design notes:**
-- Variance-sign coloring (diverging palette) is design intent only. Render bars/matrix with theme/default colors unless a tested PBIR formatting implementation is available.
-- The bottom matrix is short (144px) so it acts as a "heatmap strip" rather than a scrollable table.

package/src/content/skills/bi-report/references/layouts/generic.md

@@ -1,46 +0,0 @@
-# Generic layout (3 pages) — fallback
-
-Use when `{domain}` is "otro" or unrecognized. Extract the "main" measure and "main" dimension from the model via MCP (usually the first fact-table measure and the first non-date dim column).
-
-Roles:
-- `primary-measure`, `secondary-measure`, `tertiary-measure` (whatever the model has)
-- `primary-dim-column`, `secondary-dim-column`
-
----
-
-## Page 1: `Resumen` / "Resumen"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Resumen" |
-| KPI 1 | card | 16, 80, 280, 120 | `primary-measure` |
-| KPI 2 | card | 312, 80, 280, 120 | `secondary-measure` |
-| KPI 3 | card | 608, 80, 280, 120 | `tertiary-measure` (or omit and widen KPI1) |
-| KPI 4 | card | 904, 80, 280, 120 | any YoY / variance measure available, else omit |
-| Main trend | line_chart | 16, 216, 816, 320 | `primary-measure` × `time-dim-column` |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 216, 336, 80 | `'Date'[Year]` |
-| Primary dim slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 312, 336, 80 | `primary-dim-column` |
-
-If the model has no `Date` table at all, drop the line chart and replace with a second bar chart.
-
----
-
-## Page 2: `Analisis` / "Análisis"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Análisis" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| By primary dim | bar_chart | 16, 176, 608, 480 | `primary-measure` by `primary-dim-column` |
-| By secondary dim | bar_chart | 640, 176, 544, 480 | `primary-measure` by `secondary-dim-column` |
-
----
-
-## Page 3: `Detalle` / "Detalle"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Detalle" |
-| Primary dim slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `primary-dim-column` |
-| Secondary dim slicer | slicer (manual JSON — see `references/slicer.md`) | 312, 80, 280, 80 | `secondary-dim-column` |
-| Detail matrix | matrix | 16, 176, 1168, 480 | rows: `primary-dim-column`, cols: `secondary-dim-column`, values: `primary-measure` + `secondary-measure` |

package/src/content/skills/bi-report/references/layouts/hr.md

@@ -1,48 +0,0 @@
-# HR / People layout (3 pages)
-
-Assumed fact table: `HeadcountSnapshot` (or `EmployeeFact`). Dims: `Date`, `Employee`, `Department`, `Position`. Measures: headcount, hires, terminations, attrition rate, avg tenure, avg comp.
-
-Roles:
-- `headcount-measure`, `hires-measure`, `terminations-measure`, `attrition-rate-measure`
-- `department-dim-column`, `position-dim-column`
-
----
-
-## Page 1: `ResumenPlantilla` / "Resumen de plantilla"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Resumen de plantilla" |
-| KPI — Headcount | card | 16, 80, 280, 120 | `headcount-measure` |
-| KPI — Hires YTD | card | 312, 80, 280, 120 | `hires-measure` |
-| KPI — Terminations YTD | card | 608, 80, 280, 120 | `terminations-measure` |
-| KPI — Attrition % | card + conditional color | 904, 80, 280, 120 | `attrition-rate-measure` (red above threshold) |
-| Headcount over time | line_chart | 16, 216, 816, 320 | `headcount-measure` × `time-dim-column` |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 216, 336, 80 | `'Date'[Year]` |
-| Department slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 312, 336, 80 | `department-dim-column` |
-
----
-
-## Page 2: `AnalisisDepartamento` / "Análisis por departamento"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Análisis por departamento" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| Headcount by dept | bar_chart (horizontal) | 16, 176, 608, 480 | `headcount-measure` by `department-dim-column` |
-| Attrition by dept | bar_chart (horizontal) | 640, 176, 544, 480 | `attrition-rate-measure` by `department-dim-column` with diverging color |
-
-**Design notes:** Attrition chart colors bars by value (higher = redder) to surface hotspots immediately.
-
----
-
-## Page 3: `DetalleEmpleados` / "Detalle de empleados"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Detalle de empleados" |
-| Department slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `department-dim-column` |
-| Position slicer | slicer (manual JSON — see `references/slicer.md`) | 312, 80, 280, 80 | `position-dim-column` |
-| Employee matrix | matrix | 16, 176, 1168, 480 | rows: `Employee[FullName]`, cols: `'Date'[Year]`, values: `headcount-measure` (as snapshot) + tenure if available |
-
-**Design notes:** If the model has PII, strongly suggest adding RLS (`/bi-connect` → MCP) before sharing. Surface this to the user during kickoff.

package/src/content/skills/bi-report/references/layouts/marketing.md

@@ -1,45 +0,0 @@
-# Marketing layout (3 pages)
-
-Assumed fact: `Campaigns` / `MarketingSpend`. Dims: `Date`, `Channel`, `Audience`, `Product` / `Campaign`. Measures: spend, impressions, clicks, conversions, CPA, ROAS, CTR, conversion rate.
-
-Roles:
-- `spend-measure`, `conversions-measure`, `cpa-measure`, `roas-measure`
-- `ctr-measure`, `conversion-rate-measure`
-- `channel-dim-column`, `campaign-dim-column`, `audience-dim-column`
-
----
-
-## Page 1: `ResumenMarketing` / "Resumen de marketing"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Resumen de marketing" |
-| KPI — Spend | card | 16, 80, 280, 120 | `spend-measure` |
-| KPI — Conversions | card | 312, 80, 280, 120 | `conversions-measure` |
-| KPI — CPA | card | 608, 80, 280, 120 | `cpa-measure` |
-| KPI — ROAS | card + conditional | 904, 80, 280, 120 | `roas-measure` (green > 1, red < 1) |
-| Spend trend | line_chart | 16, 216, 816, 320 | `spend-measure` × `time-dim-column` |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 216, 336, 80 | `'Date'[Year]` |
-| Channel slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 312, 336, 80 | `channel-dim-column` |
-
----
-
-## Page 2: `AnalisisCanal` / "Análisis por canal"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Análisis por canal" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| Spend by channel | bar_chart | 16, 176, 608, 480 | `spend-measure` by `channel-dim-column` |
-| ROAS by channel | bar_chart | 640, 176, 544, 480 | `roas-measure` by `channel-dim-column`, diverging color |
-
----
-
-## Page 3: `FunnelCampañas` / "Funnel por campaña"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Funnel por campaña" |
-| Channel slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `channel-dim-column` |
-| Audience slicer | slicer (manual JSON — see `references/slicer.md`) | 312, 80, 280, 80 | `audience-dim-column` |
-| Campaign matrix | matrix | 16, 176, 1168, 480 | rows: `campaign-dim-column`, values: `spend-measure` + `conversions-measure` + `ctr-measure` + `conversion-rate-measure` + `cpa-measure` with column conditional color |

package/src/content/skills/bi-report/references/layouts/operations.md

@@ -1,44 +0,0 @@
-# Operations / Supply Chain layout (3 pages)
-
-Assumed fact: `Orders` or `Shipments`. Dims: `Date`, `Customer`, `Product`, `Facility`. Measures: volume (orders/units), SLA %, open orders, aging.
-
-Roles:
-- `volume-measure`, `sla-measure`, `open-orders-measure`, `aging-measure`
-- `facility-dim-column`, `product-dim-column`
-
----
-
-## Page 1: `ResumenOperaciones` / "Resumen operacional"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Resumen operacional" |
-| KPI — Volume | card | 16, 80, 280, 120 | `volume-measure` |
-| KPI — SLA % | card + conditional | 312, 80, 280, 120 | `sla-measure` (red below target) |
-| KPI — Open orders | card | 608, 80, 280, 120 | `open-orders-measure` |
-| KPI — Aging (avg days) | card | 904, 80, 280, 120 | `aging-measure` |
-| Volume trend | line_chart | 16, 216, 816, 320 | `volume-measure` × `time-dim-column` |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 216, 336, 80 | `'Date'[Year]` |
-| Facility slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 312, 336, 80 | `facility-dim-column` |
-
----
-
-## Page 2: `AnalisisFacility` / "Análisis por facility"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Análisis por facility" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| SLA by facility | bar_chart | 16, 176, 608, 480 | `sla-measure` by `facility-dim-column`, diverging color (red below target) |
-| Volume by facility | bar_chart | 640, 176, 544, 480 | `volume-measure` by `facility-dim-column` |
-
----
-
-## Page 3: `DetalleOrdenes` / "Detalle de órdenes"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Detalle de órdenes" |
-| Facility slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `facility-dim-column` |
-| Status slicer | slicer (manual JSON — see `references/slicer.md`) | 312, 80, 280, 80 | order status column if present |
-| Orders matrix | matrix | 16, 176, 1168, 480 | rows: `product-dim-column` + `facility-dim-column`, values: `volume-measure` + `open-orders-measure` + `aging-measure` with gradient |

package/src/content/skills/bi-report/references/layouts/sales.md

@@ -1,50 +0,0 @@
-# Sales / Revenue layout (3 pages)
-
-Assumed fact table: `Sales`. Common dims: `Date`, `Customer`, `Product`, `Salesperson`. Key measures: revenue, units, AOV, orders, revenue YoY.
-
-Roles:
-- `primary-kpi` — revenue total
-- `secondary-kpi-1/2/3` — units, orders, AOV
-- `yoy-measure` — revenue YoY %
-- `customer-dim-column`, `product-dim-column`, `salesperson-dim-column`
-
----
-
-## Page 1: `ResumenVentas` / "Resumen de ventas"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Resumen de ventas" |
-| KPI 1 — revenue | card | 16, 80, 280, 120 | `primary-kpi` |
-| KPI 2 — units | card | 312, 80, 280, 120 | `secondary-kpi-1` |
-| KPI 3 — orders | card | 608, 80, 280, 120 | `secondary-kpi-2` |
-| KPI 4 — YoY % | card + conditional color | 904, 80, 280, 120 | `yoy-measure` (signed) |
-| Revenue over time | line_chart | 16, 216, 816, 320 | `primary-kpi` × `time-dim-column` |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 216, 336, 80 | `'Date'[Year]` |
-| Channel / Segment slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 312, 336, 80 | best available segmentation column |
-
----
-
-## Page 2: `ClientesProductos` / "Clientes y productos"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Clientes y productos" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| Top customers bar | bar_chart (horizontal) | 16, 176, 608, 480 | `primary-kpi` by `customer-dim-column`, TopN 10 |
-| Top products bar | bar_chart (horizontal) | 640, 176, 544, 480 | `primary-kpi` by `product-dim-column`, TopN 10 |
-
-**Design notes:** Both bar charts share the year slicer. Use descending sort.
-
----
-
-## Page 3: `PipelineDetalle` / "Pipeline y detalle"
-
-| Visual | Primitive | Position | Bindings |
-|---|---|---|---|
-| Page title | textbox (manual JSON — see `references/textbox.md`) | 16, 16, 1152, 48 | "Pipeline y detalle" |
-| Year slicer | slicer (manual JSON — see `references/slicer.md`) | 16, 80, 280, 80 | `'Date'[Year]` |
-| Salesperson slicer | slicer (manual JSON — see `references/slicer.md`) | 312, 80, 280, 80 | `salesperson-dim-column` |
-| Pipeline matrix | matrix | 16, 176, 1168, 480 | rows: `salesperson-dim-column`, cols: `'Date'[Month]`, values: `primary-kpi` + `secondary-kpi-2` |
-
-**Design notes:** Matrix uses conditional color scale on revenue column. Subtotals enabled.