bi-superpowers 1.0.0

package/skills/bi-powerquery/references/base-template-data-contract.md

@@ -0,0 +1,323 @@
+# Base Template Data Contract
+
+`templates/base-template/base-template.pbip` is the canonical demo report. It ships demo data only, with `Data = "Demo"` on appendable business tables. The `/bi-powerquery` workflow creates real staging queries in the user's live model through Power BI Modeling MCP and sets `Data = "Real"` there. Do not add those `*_Real` queries to the template source.
+
+## Appendable Tables
+
+These are the packaged `base-template` Andina Nexus demo tables. Andina Nexus is a broader product-and-services company, not a sales-only sample. In projects generated by `/bi-kickoff`, do not assume these names still exist; discover appendable business tables from the current model instead.
+
+The packaged demo queries are organized for teaching clarity:
+
+- `Sample Dataset\Dimensiones`: dimension queries such as `Clientes`, `Productos`, `Canales`, `Servicios`, `Proyectos`, `Equipos`, and `Campañas`.
+- `Sample Dataset\Hechos`: fact queries such as `Ventas`, `Oportunidades`, `Leads`, `Movimientos financieros`, `Horas`, `Nómina`, `Ejecución proyectos`, and `Tareas proyecto`.
+
+Real staging queries created by `/bi-powerquery` must not go into those packaged sample groups. Use a separate group such as `Real Data` when authoring user-side `*_Real` queries.
+
+| Table | Purpose | Relationship contract |
+|---|---|---|
+| `Clientes` | Customer dimension | Uses `ClienteId` |
+| `Productos` | Product and serviceable-product dimension | Uses `ProductoId` |
+| `Canales` | Sales, marketing, and service channel dimension | Uses `CanalId` |
+| `Servicios` | Service catalog dimension | Uses `ServicioId` |
+| `Proyectos` | Project dimension | Uses `ProyectoId` |
+| `Equipos` | Internal team dimension | Uses `EquipoId` |
+| `Campañas` | Marketing campaign dimension | Uses `CampañaId` |
+| `Ventas` | Revenue fact | Uses `Fecha`, `ProductoId`, `ClienteId`, and `CanalId` |
+| `Oportunidades` | Pipeline fact | Uses `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, and `ServicioId` |
+| `Leads` | Marketing demand fact | Uses `Fecha`, `CampañaId`, `CanalId`, and `ClienteId` |
+| `Interacciones clientes` | Customer health fact | Uses `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, and `ServicioId` |
+| `Entregas` | Delivery fact | Uses `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, and `ServicioId` |
+| `Órdenes servicio` | Service operations fact | Uses `Fecha`, `ClienteId`, `ProductoId`, `ServicioId`, and `EquipoId` |
+| `Movimientos financieros` | Finance movement fact | Uses `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `ServicioId`, `ProyectoId`, and `EquipoId` |
+| `Presupuesto` | Budget fact | Uses `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `ServicioId`, `ProyectoId`, and `EquipoId` |
+| `Devoluciones` | Product return fact | Uses `Fecha`, `ClienteId`, `CanalId`, and `ProductoId` |
+| `Horas` | People capacity fact | Uses `Fecha`, `EquipoId`, `ProyectoId`, and `ServicioId` |
+| `Nómina` | People cost fact | Uses `Fecha`, `EquipoId`, `ProyectoId`, and `ServicioId` |
+| `Ejecución proyectos` | Project execution fact | Uses `Fecha`, `ProyectoId`, `ClienteId`, `ServicioId`, and `EquipoId` |
+| `Tareas proyecto` | Project task fact | Uses `Fecha`, `ProyectoId`, and `EquipoId` |
+
+## Demo ID Contract
+
+The template avoids Demo/Real collisions by making demo IDs text values with an entity-coded prefix:
+
+```text
+ClienteA01R
+ProductoA01S
+CanalA01P
+```
+
+The original ID columns remain the relationship columns. Packaged demo queries generate stable codes from the entity name plus a deterministic alphanumeric suffix:
+
+```powerquery
+ClienteId = EntityCode("Cliente", [ClienteId])
+ProductoId = EntityCode("Producto", [ProductoId])
+CanalId = EntityCode("Canal", [CanalId])
+```
+
+The suffix is intentionally readable in demos: `EntityCode("Cliente", 25)` returns `ClienteA25D`. This keeps relationship keys stable without exposing generic `Demo#########` values in teaching views or drill-through tables.
+
+Do not add extra key columns for this split. Real staging queries keep the user's source IDs in the same columns, converted to text, and add only `Data = "Real"`.
+
+## Generated Domain Models
+
+When `/bi-kickoff` has replaced the packaged Andina Nexus sample with another domain (finance, habits, inventory, logistics, HR, etc.), `/bi-powerquery` must discover appendable business tables from the project itself:
+
+- Read `AGENTS.md` and `docs/mapeo-de-datos.md` when present.
+- Inspect loaded business tables that expose a visible `Data` column with demo rows.
+- Inspect relationships from fact tables to `Calendario` and business dimensions.
+- Use the existing table columns as the destination contract.
+- Keep the table name stable and append real rows into that same table through a `*_Real` staging query.
+
+The bundled staging generator supports this mode by passing the discovered schema:
+
+```powershell
+.\scripts\new-powerquery-staging.ps1 `
+  -TableName "Inventario semanal" `
+  -SourceExpression 'Excel.CurrentWorkbook(){[Name="Inventario"]}[Content]' `
+  -RequiredColumns InventarioId,Fecha,StockDisponible `
+  -ColumnTypesJson '{"InventarioId":"type text","Fecha":"type date","StockDisponible":"type number"}'
+```
+
+Do not force generated projects back into `Ventas`, `Clientes`, `Productos`, or `Canales`.
+
+## Source Columns
+
+Column names in this section are Power Query source-column names. Some display names in the model are friendlier, for example `Pais` can display as `País`, but the staging contract uses the source column.
+
+`Clientes` real source columns:
+- `ClienteId`
+- `Cliente`
+- `Segmento`
+- `Pais`
+
+`Productos` real source columns:
+- `ProductoId`
+- `Producto`
+- `Categoria`
+- `Subcategoria`
+
+`Canales` real source columns:
+- `CanalId`
+- `Canal`
+- `Tipo de canal`
+
+`Servicios` real source columns:
+- `ServicioId`
+- `Servicio`
+- `Línea servicio`
+- `Modalidad`
+
+`Proyectos` real source columns:
+- `ProyectoId`
+- `Proyecto`
+- `Tipo proyecto`
+- `Estado proyecto`
+
+`Equipos` real source columns:
+- `EquipoId`
+- `Equipo`
+- `Área equipo`
+- `Seniority`
+
+`Campañas` real source columns:
+- `CampañaId`
+- `Campaña`
+- `Canal marketing`
+- `Objetivo campaña`
+
+`Ventas` real source columns:
+- `VentaId`
+- `Fecha`
+- `ProductoId`
+- `ClienteId`
+- `CanalId`
+- `Moneda`
+- `Cantidad`
+- `Precio Unitario`
+- `Costo Unitario`
+- `Venta Bruta`
+- `Costo Total`
+- `Venta Bruta Base`
+- `Costo Total Base`
+
+`Oportunidades` real source columns:
+- `OportunidadId`
+- `Fecha`
+- `ClienteId`
+- `CanalId`
+- `ProductoId`
+- `ServicioId`
+- `Estado`
+- `Importe Potencial Base`
+- `Probabilidad`
+
+`Leads` real source columns:
+- `LeadBatchId`
+- `Fecha`
+- `CampañaId`
+- `CanalId`
+- `ClienteId`
+- `Leads`
+- `MQLs`
+- `Clientes ganados`
+- `Costo Base`
+- `Ventas Atribuidas Base`
+
+`Interacciones clientes` real source columns:
+- `InteraccionId`
+- `Fecha`
+- `ClienteId`
+- `CanalId`
+- `ProductoId`
+- `ServicioId`
+- `Clientes Inicio`
+- `Clientes Perdidos`
+- `NPS`
+- `Reclamos`
+- `Tiempo Respuesta Horas`
+
+`Entregas` real source columns:
+- `EntregaId`
+- `Fecha`
+- `ClienteId`
+- `CanalId`
+- `ProductoId`
+- `ServicioId`
+- `Entregas`
+- `Entregas A Tiempo`
+
+`Órdenes servicio` real source columns:
+- `OrdenServicioId`
+- `Fecha`
+- `ClienteId`
+- `ProductoId`
+- `ServicioId`
+- `EquipoId`
+- `Órdenes`
+- `Órdenes Completadas`
+- `Backlog`
+- `Tiempo Ciclo Días`
+- `SLA Cumplido`
+- `Retrabajos`
+- `Horas Usadas`
+- `Horas Disponibles`
+- `Servicios Adjuntos`
+
+`Movimientos financieros` real source columns:
+- `MovimientoId`
+- `Fecha`
+- `ClienteId`
+- `CanalId`
+- `ProductoId`
+- `ServicioId`
+- `ProyectoId`
+- `EquipoId`
+- `Tipo movimiento`
+- `Importe Base`
+
+`Presupuesto` real source columns:
+- `PresupuestoId`
+- `Fecha`
+- `ClienteId`
+- `CanalId`
+- `ProductoId`
+- `ServicioId`
+- `ProyectoId`
+- `EquipoId`
+- `Área presupuesto`
+- `Importe Presupuesto Base`
+
+`Devoluciones` real source columns:
+- `DevolucionId`
+- `Fecha`
+- `ClienteId`
+- `CanalId`
+- `ProductoId`
+- `Unidades Devueltas`
+
+`Horas` real source columns:
+- `HoraId`
+- `Fecha`
+- `EquipoId`
+- `ProyectoId`
+- `ServicioId`
+- `Horas Planificadas`
+- `Horas Trabajadas`
+- `Horas Facturables`
+- `Horas Disponibles`
+- `Horas Ausentes`
+
+`Nómina` real source columns:
+- `NominaId`
+- `Fecha`
+- `EquipoId`
+- `ProyectoId`
+- `ServicioId`
+- `Headcount`
+- `Costo Laboral Base`
+- `Bajas`
+
+`Ejecución proyectos` real source columns:
+- `EjecucionProyectoId`
+- `Fecha`
+- `ProyectoId`
+- `ClienteId`
+- `ServicioId`
+- `EquipoId`
+- `Estado ejecución`
+- `Avance`
+- `Ingresos Base`
+- `Costos Base`
+- `Presupuesto Base`
+
+`Tareas proyecto` real source columns:
+- `TareaProyectoId`
+- `Fecha`
+- `ProyectoId`
+- `EquipoId`
+- `Tareas`
+- `Tareas Vencidas`
+- `Horas`
+
+## Generated Columns
+
+Every real staging query must add only:
+
+```powerquery
+Data = "Real"
+```
+
+ID columns are converted to text so they can append cleanly to the demo tables.
+
+## Relationships
+
+Power BI relationships stay on the original ID columns:
+
+- `Ventas[ProductoId]` -> `Productos[ProductoId]`
+- `Ventas[ClienteId]` -> `Clientes[ClienteId]`
+- `Ventas[CanalId]` -> `Canales[CanalId]`
+- `Ventas[Fecha]` -> `Calendario[Fecha]`
+- `Leads[CampañaId]` -> `Campañas[CampañaId]`
+- `Oportunidades[ServicioId]` -> `Servicios[ServicioId]`
+- `Interacciones clientes[ServicioId]` -> `Servicios[ServicioId]`
+- `Movimientos financieros[ProyectoId]` -> `Proyectos[ProyectoId]`
+- `Presupuesto[EquipoId]` -> `Equipos[EquipoId]`
+- `Horas[ProyectoId]` -> `Proyectos[ProyectoId]`
+- `Ejecución proyectos[ProyectoId]` -> `Proyectos[ProyectoId]`
+- `Tareas proyecto[EquipoId]` -> `Equipos[EquipoId]`
+
+## Non-Appendable Tables
+
+Do not append real business rows into these framework tables as part of `/bi-powerquery`:
+
+- `Calendario`
+- `Métricas`
+- `Equipos métricas`
+- `_Aux *`
+- `_GC *`
+- `_PC *`
+- `_Aux Modelo configuración`
+- `Monedas`
+- `Tipo de cambio`
+
+These tables are semantic/report infrastructure. Extend them only through a dedicated modeling task.

package/skills/bi-powerquery/references/power-query-standards.md

@@ -0,0 +1,74 @@
+# Power Query Standards
+
+## Contract First
+
+- Validate required source columns before selecting, transforming, or appending.
+- Keep final column order deterministic and identical to the base-template contract.
+- Fail loudly when required columns are missing. Do not create placeholder business fields silently.
+- Do not use `MissingField.UseNull` or `MissingField.Ignore` in generated staging queries. Microsoft Learn documents those options as missing-column fallbacks; this workflow wants missing columns to fail because a silent null column would corrupt relationships and measures.
+- Add or overwrite `Data = "Real"` inside the real staging query, not after append. If the source already has a `Data` column, replace its values with `Real` instead of keeping user-supplied source labels.
+
+## Types
+
+- Use `Table.TransformColumnTypes` with an explicit culture such as `"en-US"` when parsing IDs, dates, and numbers.
+- Use `type text` for relationship IDs so real rows can append to the demo tables, whose IDs are entity-coded text values such as `ClienteA25D`.
+- Use `Int64.Type` for counts.
+- Use `type number` for monetary/decimal values.
+- For dates, match the `Calendario` key type **exactly** and strip any time component (e.g. `Date.From([Fecha])` or `type date`). A `datetime` carrying a non-midnight time silently fails to match `Calendario[Fecha]` — the engine compares the full datetime, so those rows won't join and time-intelligence goes blank/wrong.
+
+## Query Shape
+
+Recommended real staging shape:
+
+```powerquery
+let
+    Source = ...,
+    RequiredColumns = {...},
+    MissingColumns = List.Difference(RequiredColumns, Table.ColumnNames(Source)),
+    AssertRequiredColumns = if List.Count(MissingColumns) = 0 then Source else error Error.Record("MissingColumns", "Source is missing required columns.", MissingColumns),
+    Typed = Table.TransformColumnTypes(AssertRequiredColumns, {...}, "en-US"),
+    AddData = if Table.HasColumns(Typed, "Data") then Table.TransformColumns(Typed, {{"Data", each "Real", type text}}) else Table.AddColumn(Typed, "Data", each "Real", type text),
+    Result = Table.SelectColumns(AddData, {...})
+in
+    Result
+```
+
+## MCP Authoring Contract
+
+PBIP/TMDL files are read-only snapshots. Use them to inspect the current model,
+compare output, and validate the saved result; do not edit them directly when a
+live Power BI Desktop model is open.
+
+Live Power Query changes must go through Power BI Modeling MCP:
+
+- Use `query_group_operations` to create or reuse a helper query group.
+- Use `named_expression_operations` to create or update unloaded `*_Real` M
+  staging queries.
+- Use `partition_operations` to update the loaded table partition that appends
+  Demo + Real.
+- Refresh data from **Power BI Desktop** (`Inicio ▶ Actualizar`, or `Aplicar
+  cambios` when Power Query has pending changes). Microsoft does not support
+  processing/refresh commands against a model open in Desktop, so do not try to
+  refresh data through the MCP — author metadata via MCP, then let Desktop load
+  the data.
+- Save Power BI Desktop before claiming persistence.
+- Use `database_operations` / `ExportToTmdlFolder` only after save/export to
+  inspect and validate the snapshot Desktop wrote.
+
+If the MCP surface cannot author the required object, guide the user through
+Power BI Desktop for that step. Do not patch `.tmdl`, `.SemanticModel/**`, or
+partition files as a workaround.
+
+## Refresh Hygiene
+
+- Keep `*_Real` staging queries unloaded after they feed the loaded template table.
+- Keep credentials and privacy levels explicit. Do not mix local files, web APIs, and organizational sources casually in the same query.
+- Preserve query folding for SQL and Fabric sources by pushing filters and type operations as close to the source as possible.
+- Avoid hard-coded local user paths in reusable skill output; parameterize paths or ask the user for a project-local location.
+- Write generated `.m` snippets only to scratch folders such as `.\powerquery-output`; never place them inside `pbip-files/`, `*.SemanticModel`, `*.Report`, `.pbi`, `DAXQueries`, or `TMDLScripts`. Those locations are Power BI project artifacts, not agent scratch space.
+
+## Agent Behavior
+
+- Explain the Demo/Real split while editing so the user understands why `Data` exists.
+- Summarize generated M and validation results; only paste full M when the user asks.
+- Use Power BI Modeling MCP for live semantic-model writes and Desktop save/export for persistence.