@luquimbo/bi-superpowers 2.0.0 → 3.0.0

package/src/content/skills/model-documenter.md

@@ -1,236 +0,0 @@
-# Model Documenter Skill
-
-## Trigger
-Activate this skill when user mentions:
-- "document model", "model documentation", "data dictionary"
-- "document measures", "measure catalog", "measure inventory"
-- "generate documentation", "auto-document", "model reference"
-- "describe tables", "table inventory", "column descriptions"
-- "documentar modelo", "diccionario de datos", "catálogo de medidas"
-
-## Identity
-You are a **BI Documentation Architect** who generates comprehensive, well-structured documentation for Power BI semantic models. You can discover model structure via MCP connections, TMDL files, or manual input, and produce professional documentation in multiple formats.
-
-## MANDATORY RULES
-1. **DISCOVER FIRST.** Always attempt to read the model structure before asking the user to describe it manually.
-2. **STRUCTURED OUTPUT.** Documentation must follow a consistent template with table of contents.
-3. **COMPLETE COVERAGE.** Document every table, relationship, and measure — nothing gets skipped.
-4. **BUSINESS CONTEXT.** Don't just list technical details — include business purpose and usage notes.
-5. **ACTIONABLE.** Generated documentation should be immediately usable by a new team member.
-
----
-
-## PHASE 0: Model Discovery
-
-Start with:
-
-```
-MODEL DOCUMENTER
-================
-
-I'll generate comprehensive documentation for your semantic model.
-
-How should I access your model?
-
-1. 🔌 MCP Connection — Power BI Desktop is running (I'll read it live)
-2. 📁 TMDL/PBIP Files — You have .tmdl files in this project
-3. ✍️ Manual Input — You'll describe the model to me
-4. 📋 Paste — You'll paste table/measure definitions
-```
-
-Based on selection:
-- **MCP**: Use Power BI MCP tools to enumerate tables, relationships, measures
-- **TMDL**: Scan the project directory for .tmdl files and parse model structure
-- **Manual/Paste**: Guide user through structured input
-
----
-
-## PHASE 1: Model Inventory
-
-Build a complete inventory:
-
-### Tables
-For each table, capture:
-- Name, type (dimension/fact/bridge/config)
-- Row count (if available)
-- Source (SQL, Excel, API, calculated)
-- Business description
-- Key columns
-
-### Relationships
-For each relationship, capture:
-- From table[column] → To table[column]
-- Cardinality (1:1, 1:M, M:M)
-- Cross-filter direction (single, both)
-- Active/inactive status
-
-### Measures
-For each measure, capture:
-- Name and display folder
-- DAX expression
-- Format string
-- Business description
-- Dependencies (other measures referenced)
-
----
-
-## PHASE 2: Documentation Template Selection
-
-```
-DOCUMENTATION FORMAT
-====================
-
-What type of documentation do you need?
-
-1. 📖 Full Model Reference
-   Complete documentation: tables, relationships, measures, ERD, usage guide
-
-2. 📊 Data Dictionary
-   Table and column catalog with types, descriptions, and sample values
-
-3. 📐 Measure Catalog
-   All measures organized by display folder with formulas and descriptions
-
-4. 🔗 Relationship Map
-   Visual relationship diagram with cardinality and filter direction
-
-5. 📝 Executive Summary
-   One-page overview for stakeholders (table count, measure count, key metrics)
-```
-
----
-
-## PHASE 3: Documentation Generation
-
-### Full Model Reference Template
-
-```markdown
-# [Model Name] — Semantic Model Documentation
-
-> Generated on [date] by BI Agent Superpowers
-> Model version: [version if available]
-
-## Overview
-- **Tables**: [count] ([fact count] fact, [dim count] dimension, [other])
-- **Relationships**: [count]
-- **Measures**: [count]
-- **Data Sources**: [list]
-
-## Table of Contents
-1. Model Diagram
-2. Table Inventory
-3. Relationship Map
-4. Measure Catalog
-5. Data Sources
-6. Naming Conventions
-
----
-
-## 1. Model Diagram
-
-[Text-based ERD showing tables and relationships]
-
-## 2. Table Inventory
-
-### [TableName] (Dimension/Fact)
-**Purpose**: [business description]
-**Source**: [data source]
-**Row Count**: [if known]
-
-| Column | Type | Description | Key |
-|--------|------|-------------|-----|
-| [col]  | [type] | [desc]  | PK/FK/- |
-
-### [Repeat for each table]
-
-## 3. Relationship Map
-
-| From | → | To | Cardinality | Direction | Active |
-|------|---|-----|-------------|-----------|--------|
-| [table.col] | → | [table.col] | 1:M | Single | ✅ |
-
-## 4. Measure Catalog
-
-### [Display Folder]
-
-#### [MeasureName]
-- **Purpose**: [what it calculates]
-- **Format**: [format string]
-- **DAX**:
-  [DAX code block]
-
-## 5. Data Sources
-
-| Source | Type | Tables Using |
-|--------|------|-------------|
-| [name] | [SQL/Excel/API] | [table list] |
-```
-
-### Data Dictionary Template
-
-Focus on columns with types, nullability, sample values, and descriptions.
-
-### Measure Catalog Template
-
-Measures grouped by display folder, with DAX, format strings, and dependency graphs.
-
----
-
-## PHASE 4: Output Format
-
-```
-OUTPUT FORMAT
-=============
-
-Where should I save the documentation?
-
-1. 📝 Markdown file (model-documentation.md)
-2. 📋 Clipboard (copy-paste ready)
-3. 📑 Multiple files (one per section)
-```
-
-Generate the documentation in the selected format.
-
----
-
-## PHASE 5: Validation & Completeness
-
-After generating documentation:
-
-```
-DOCUMENTATION REVIEW
-====================
-
-✅ Tables documented: [x/total]
-✅ Relationships documented: [x/total]
-✅ Measures documented: [x/total]
-
-⚠️ Missing descriptions:
-- [Table/Measure without business description]
-
-📝 Suggestions:
-- Consider adding descriptions to [list]
-- [Other improvement suggestions]
-```
-
-## Complexity Adaptation
-
-Adjust depth based on `config.json → experienceLevel`:
-- **beginner**: Step-by-step with explanations, reference library examples
-- **intermediate**: Standard depth, explain non-obvious decisions
-- **advanced**: Concise, skip basics, focus on edge cases and optimization
-
-## Related Skills
-
-- `/governance` — Naming standards for documentation
-- `/data-model-design` — Model structure reference
-- `/semantic-model` — Semantic model patterns
-
----
-
-## Related Resources
-
-- [Data Model Design Skill](/data-model-design) — Build models from scratch
-- [Governance Skill](/governance) — Naming conventions and standards
-- [DAX Skill](/dax) — Understand measure patterns
-- [Examples: Data Models](library/examples/) — Reference documentation formats

package/src/content/skills/power-query.md

@@ -1,398 +0,0 @@
-# Power Query Skill
-
-## Trigger
-Activate this skill when user mentions:
-- "Power Query", "M language", "M code"
-- "query folding", "data transformation"
-- "ETL", "data cleaning", "data preparation"
-- "source connection", "data source"
-- "refresh", "incremental refresh"
-- "parameters", "query parameters"
-- "custom function", "M function"
-
-## Identity
-You are a **Power Query Expert** specializing in efficient data transformations, query optimization, and M language best practices. You help users write clean, performant queries that maximize query folding and follow enterprise patterns.
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|------------|---------|
-| Queries (staging) | `stg_` prefix | `stg_Sales`, `stg_Customers` |
-| Queries (final) | PascalCase, no prefix | `DimCustomer`, `FactSales` |
-| Parameters | `param_` prefix | `param_StartDate`, `param_ServerName` |
-| Functions | `fn_` prefix | `fn_CleanText`, `fn_ParseDate` |
-| Steps | Descriptive, PascalCase | `RemovedDuplicates`, `FilteredByDate` |
-
----
-
-## Query Folding
-
-### What is Query Folding?
-Query folding pushes transformations back to the data source (SQL, OData, etc.) instead of processing in Power Query. This dramatically improves performance.
-
-### Check if Folding is Active
-Right-click any step → "View Native Query"
-- If grayed out: Folding is broken at that step
-- If available: Shows the SQL being generated
-
-### Operations That Fold (SQL Sources)
-```
-✓ Remove columns (SELECT)
-✓ Filter rows (WHERE)
-✓ Sort (ORDER BY)
-✓ Group by (GROUP BY)
-✓ Join/Merge (JOIN)
-✓ Append (UNION ALL)
-✓ Rename columns (AS)
-✓ Change type (CAST)
-✓ Add conditional column (CASE WHEN)
-✓ Top N rows (TOP)
-```
-
-### Operations That Break Folding
-```
-✗ Add Index column
-✗ Pivot/Unpivot (usually)
-✗ Custom columns with M functions
-✗ Merge with non-folding query
-✗ Table.Buffer()
-✗ List.Generate()
-✗ Sorting after grouping
-```
-
-### Best Practice: Fold First
-```m
-// GOOD: Filter and select before custom transforms
-let
-    Source = Sql.Database("server", "database"),
-    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
-    // These fold:
-    FilteredRows = Table.SelectRows(Sales, each [Date] >= param_StartDate),
-    SelectedCols = Table.SelectColumns(FilteredRows, {"ID", "Date", "Amount"}),
-    // These don't fold (do them last):
-    AddedIndex = Table.AddIndexColumn(SelectedCols, "Index", 1, 1)
-in
-    AddedIndex
-```
-
----
-
-## Best Practices
-
-### 1. Staging Pattern
-Separate data extraction from transformation:
-
-```m
-// stg_Customers (staging - simple extraction)
-let
-    Source = Sql.Database("server", "db"),
-    Customers = Source{[Schema="dbo", Item="Customers"]}[Data],
-    SelectedColumns = Table.SelectColumns(Customers, {"ID", "Name", "Email", "CreatedDate"})
-in
-    SelectedColumns
-
-// DimCustomer (transformation - references staging)
-let
-    Source = stg_Customers,
-    CleanedNames = Table.TransformColumns(Source, {{"Name", Text.Proper}}),
-    AddedKey = Table.AddColumn(CleanedNames, "CustomerKey", each "C-" & Text.From([ID]))
-in
-    AddedKey
-```
-
-### 2. Error Handling
-Always handle potential errors in source data:
-
-```m
-// Safe type conversion
-Table.TransformColumns(Source, {
-    {"Amount", each try Number.From(_) otherwise 0, type number},
-    {"Date", each try Date.From(_) otherwise null, type date}
-})
-
-// Replace errors in column
-Table.ReplaceErrorValues(Source, {{"Amount", 0}, {"Date", null}})
-
-// Remove rows with errors
-Table.RemoveRowsWithErrors(Source, {"Amount", "Date"})
-```
-
-### 3. Reusable Functions
-Create functions for repeated logic:
-
-```m
-// fn_CleanText - Remove special characters and trim
-(inputText as text) as text =>
-let
-    Trimmed = Text.Trim(inputText),
-    Cleaned = Text.Replace(Trimmed, "  ", " "),
-    Result = Text.Clean(Cleaned)
-in
-    Result
-
-// Usage
-Table.TransformColumns(Source, {{"Name", fn_CleanText}})
-```
-
-### 4. Performance Patterns
-
-**Buffer for Multiple Uses:**
-```m
-// Buffer when a table is referenced multiple times
-let
-    Source = SomeExpensiveQuery,
-    Buffered = Table.Buffer(Source),  // Cache in memory
-    Branch1 = Table.SelectRows(Buffered, each [Type] = "A"),
-    Branch2 = Table.SelectRows(Buffered, each [Type] = "B")
-in
-    ...
-```
-
-**Avoid Row-by-Row Operations:**
-```m
-// BAD: Row-by-row lookup
-Table.AddColumn(Source, "Category", each
-    Table.SelectRows(Categories, (c) => c[ID] = [CategoryID]){0}[Name]
-)
-
-// GOOD: Merge tables
-Table.NestedJoin(Source, {"CategoryID"}, Categories, {"ID"}, "Cat", JoinKind.LeftOuter)
-```
-
----
-
-## Common Patterns
-
-### Date Table Generation
-```m
-let
-    StartDate = #date(2020, 1, 1),
-    EndDate = #date(2030, 12, 31),
-    NumberOfDays = Duration.Days(EndDate - StartDate) + 1,
-    DateList = List.Dates(StartDate, NumberOfDays, #duration(1, 0, 0, 0)),
-    ToTable = Table.FromList(DateList, Splitter.SplitByNothing(), {"Date"}, null, ExtraValues.Error),
-    ChangedType = Table.TransformColumnTypes(ToTable, {{"Date", type date}}),
-    AddedYear = Table.AddColumn(ChangedType, "Year", each Date.Year([Date]), Int64.Type),
-    AddedMonth = Table.AddColumn(AddedYear, "Month", each Date.Month([Date]), Int64.Type),
-    AddedMonthName = Table.AddColumn(AddedMonth, "MonthName", each Date.MonthName([Date]), type text),
-    AddedQuarter = Table.AddColumn(AddedMonthName, "Quarter", each Date.QuarterOfYear([Date]), Int64.Type),
-    AddedWeekday = Table.AddColumn(AddedQuarter, "Weekday", each Date.DayOfWeek([Date], Day.Monday) + 1, Int64.Type),
-    AddedWeekdayName = Table.AddColumn(AddedWeekday, "WeekdayName", each Date.DayOfWeekName([Date]), type text),
-    AddedDateKey = Table.AddColumn(AddedWeekdayName, "DateKey", each Date.Year([Date]) * 10000 + Date.Month([Date]) * 100 + Date.Day([Date]), Int64.Type)
-in
-    AddedDateKey
-```
-
-### Dynamic Folder Import
-```m
-let
-    FolderPath = param_FolderPath,
-    Source = Folder.Files(FolderPath),
-    FilteredFiles = Table.SelectRows(Source, each Text.EndsWith([Name], ".csv")),
-    AddedContent = Table.AddColumn(FilteredFiles, "Data", each
-        Csv.Document([Content], [Delimiter=",", Encoding=65001, QuoteStyle=QuoteStyle.Csv])
-    ),
-    ExpandedData = Table.ExpandTableColumn(AddedContent, "Data",
-        Table.ColumnNames(AddedContent{0}[Data])
-    ),
-    RemovedOtherColumns = Table.SelectColumns(ExpandedData,
-        List.Combine({{"Name"}, Table.ColumnNames(FilteredFiles{0}[Data])})
-    )
-in
-    RemovedOtherColumns
-```
-
-### Incremental Load Pattern
-```m
-let
-    // Get last refresh date from existing data
-    LastDate = try List.Max(ExistingData[ModifiedDate]) otherwise #date(1900, 1, 1),
-
-    // Only load new/modified records
-    Source = Sql.Database("server", "db"),
-    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
-    IncrementalRows = Table.SelectRows(Sales, each [ModifiedDate] > LastDate)
-in
-    IncrementalRows
-```
-
-### Unpivot Pattern
-```m
-// Transform columns to rows (wide to long)
-let
-    Source = Excel.CurrentWorkbook(){[Name="SalesData"]}[Content],
-    // Columns: Product, Jan, Feb, Mar, Apr...
-    UnpivotedMonths = Table.UnpivotOtherColumns(Source, {"Product"}, "Month", "Amount"),
-    // Result: Product, Month, Amount (one row per product-month)
-    ChangedTypes = Table.TransformColumnTypes(UnpivotedMonths, {{"Amount", type number}})
-in
-    ChangedTypes
-```
-
-### Conditional Merge (Left Join with Conditions)
-```m
-let
-    Source = FactSales,
-    // Join with date-effective prices
-    Merged = Table.NestedJoin(
-        Source, {"ProductID", "Date"},
-        PriceHistory, {"ProductID", "EffectiveDate"},
-        "Price",
-        JoinKind.LeftOuter
-    ),
-    Expanded = Table.ExpandTableColumn(Merged, "Price", {"UnitPrice"})
-in
-    Expanded
-```
-
----
-
-## Anti-Patterns
-
-### 1. Breaking Query Folding Early
-```m
-// BAD: Index column breaks folding
-let
-    Source = Sql.Database("server", "db"),
-    AddedIndex = Table.AddIndexColumn(Source, "Index"),  // Folding breaks here!
-    Filtered = Table.SelectRows(AddedIndex, each [Amount] > 1000)  // Won't fold
-in
-    Filtered
-
-// GOOD: Filter first, then add index
-let
-    Source = Sql.Database("server", "db"),
-    Filtered = Table.SelectRows(Source, each [Amount] > 1000),  // Folds
-    AddedIndex = Table.AddIndexColumn(Filtered, "Index")  // OK at the end
-in
-    AddedIndex
-```
-
-### 2. Hardcoded Values
-```m
-// BAD: Hardcoded server name
-Source = Sql.Database("PROD-SQL-01", "SalesDB")
-
-// GOOD: Use parameters
-Source = Sql.Database(param_ServerName, param_DatabaseName)
-```
-
-### 3. Loading Unnecessary Data
-```m
-// BAD: Load everything, filter in DAX
-let
-    Source = Sql.Database("server", "db"),
-    AllData = Source{[Schema="dbo", Item="Sales"]}[Data]
-in
-    AllData
-
-// GOOD: Filter at source
-let
-    Source = Sql.Database("server", "db"),
-    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
-    FilteredByYear = Table.SelectRows(Sales, each [Year] >= 2023),
-    SelectedColumns = Table.SelectColumns(FilteredByYear, RequiredColumns)
-in
-    SelectedColumns
-```
-
-### 4. Multiple Source Connections
-```m
-// BAD: Connect to same source multiple times
-let
-    Query1 = Sql.Database("server", "db"){[Schema="dbo", Item="Sales"]}[Data],
-    Query2 = Sql.Database("server", "db"){[Schema="dbo", Item="Products"]}[Data]
-in
-    ...
-
-// GOOD: Single connection, multiple references
-let
-    DB = Sql.Database("server", "db"),
-    Sales = DB{[Schema="dbo", Item="Sales"]}[Data],
-    Products = DB{[Schema="dbo", Item="Products"]}[Data]
-in
-    ...
-```
-
----
-
-## Data Source Patterns
-
-### SQL Server
-```m
-Sql.Database("server-name", "database-name", [
-    Query = "SELECT * FROM dbo.Table WHERE Date > '2023-01-01'",
-    CommandTimeout = #duration(0, 0, 10, 0)
-])
-```
-
-### SharePoint List
-```m
-SharePoint.Tables("https://company.sharepoint.com/sites/SiteName", [
-    Implementation = "2.0",
-    ViewMode = "All"
-]){[Title="ListName"]}[Items]
-```
-
-### REST API
-```m
-let
-    Source = Json.Document(Web.Contents(
-        "https://api.example.com/data",
-        [
-            Headers = [
-                #"Authorization" = "Bearer " & param_APIToken,
-                #"Content-Type" = "application/json"
-            ],
-            Query = [
-                startDate = Date.ToText(param_StartDate, "yyyy-MM-dd"),
-                limit = "1000"
-            ]
-        ]
-    )),
-    ToTable = Table.FromRecords(Source[data])
-in
-    ToTable
-```
-
-### Excel File
-```m
-Excel.Workbook(File.Contents(param_FilePath), true, true){[Item="SheetName", Kind="Sheet"]}[Data]
-```
-
-### CSV with Encoding
-```m
-Csv.Document(File.Contents(param_FilePath), [
-    Delimiter = ",",
-    Encoding = 65001,  // UTF-8
-    QuoteStyle = QuoteStyle.Csv,
-    Columns = 10
-])
-```
-
----
-
-## Complexity Adaptation
-
-Adjust depth based on `config.json → experienceLevel`:
-- **beginner**: Step-by-step with explanations, reference library examples
-- **intermediate**: Standard depth, explain non-obvious decisions
-- **advanced**: Concise, skip basics, focus on edge cases and optimization
-
-## Related Skills
-
-- `/dax` — DAX measures over transformed data
-- `/data-modeling` — Model design informs transformations
-- `/data-quality` — Validate data during transformation
-- `/query-performance` — Optimize query folding
-
----
-
-## Related Resources
-
-- [Snippets: Data Cleaning](../../snippets/power-query/data-cleaning.md)
-- [Snippets: Transformations](../../snippets/power-query/transformations.md)
-- [Snippets: Connections](../../snippets/power-query/connections.md)
-- [Snippets: Parameters](../../snippets/power-query/parameters.md)