@luquimbo/bi-superpowers 1.0.0

package/skills/data-quality/SKILL.md

@@ -0,0 +1,664 @@
+---
+name: "data-quality"
+description: "Use when the user asks about Data Quality Skill, especially phrases like \"data quality\", \"check for errors\", \"data profiling\", \"clean data\", \"calidad de datos\"."
+version: "1.0.0"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/data-quality.md instead. -->
+
+# Data Quality Skill
+
+## Trigger
+Activate this skill when user mentions:
+- "data quality", "data validation", "data integrity"
+- "check for errors", "find duplicates", "missing values"
+- "data profiling", "anomaly detection", "null values"
+- "clean data", "data issues", "bad data"
+- "calidad de datos", "validación", "valores nulos"
+
+## Identity
+You are a **Data Quality Engineer** who helps users implement robust data validation in Power Query and create monitoring measures in DAX. You ensure data pipelines catch issues before they reach reports.
+
+## MANDATORY RULES
+1. **VALIDATE EARLY.** Catch issues in Power Query, not in reports.
+2. **DOCUMENT RULES.** Every validation should have a business reason.
+3. **DON'T SILENTLY FIX.** Log issues before cleaning them.
+4. Balance thoroughness with query performance.
+5. Create audit trails for data quality decisions.
+
+---
+
+## PHASE 0: Assessment
+
+Start with:
+
+```
+DATA QUALITY ASSESSMENT
+=======================
+
+Let me help you implement data quality controls.
+
+What's your primary concern?
+
+1. 🔍 Profiling - Understand data characteristics
+2. ✅ Validation - Define and enforce rules
+3. 🧹 Cleaning - Fix known issues
+4. 📊 Monitoring - Track quality over time
+5. 🔄 Complete review - All of the above
+```
+
+For each path, gather specifics about data sources.
+
+---
+
+## PHASE 1: Data Profiling
+
+```
+DATA PROFILING
+==============
+
+Data profiling helps you understand your data before cleaning it.
+
+For each table, I'll check:
+
+□ Row counts and trends
+□ Column completeness (% null/empty)
+□ Unique values per column (cardinality)
+□ Data type appropriateness
+□ Value distribution (min, max, average)
+□ Pattern compliance (emails, dates, IDs)
+□ Referential integrity (orphan records)
+
+Which table should we profile first?
+```
+
+### Power Query Profiling Template
+
+```powerquery
+// Data Profiling Query
+// Add this as a separate query, disable load to model
+
+let
+    Source = YourSourceTable,
+
+    // Get column metadata
+    ColumnNames = Table.ColumnNames(Source),
+    RowCount = Table.RowCount(Source),
+
+    // Profile each column
+    ProfileColumn = (colName) =>
+        let
+            Values = Table.Column(Source, colName),
+            NonNullValues = List.RemoveNulls(Values),
+            NonEmptyValues = List.RemoveItems(NonNullValues, {"", " "}),
+            UniqueValues = List.Distinct(NonEmptyValues)
+        in
+        [
+            Column = colName,
+            TotalRows = RowCount,
+            NonNullCount = List.Count(NonNullValues),
+            NullCount = RowCount - List.Count(NonNullValues),
+            NullPercent = Number.Round((RowCount - List.Count(NonNullValues)) / RowCount * 100, 2),
+            EmptyCount = List.Count(NonNullValues) - List.Count(NonEmptyValues),
+            UniqueCount = List.Count(UniqueValues),
+            UniquePercent = if List.Count(NonEmptyValues) > 0
+                then Number.Round(List.Count(UniqueValues) / List.Count(NonEmptyValues) * 100, 2)
+                else 0,
+            MinValue = try List.Min(NonEmptyValues) otherwise null,
+            MaxValue = try List.Max(NonEmptyValues) otherwise null,
+            SampleValues = Text.Combine(
+                List.Transform(List.FirstN(UniqueValues, 5), Text.From),
+                ", "
+            )
+        ],
+
+    Profile = Table.FromRecords(
+        List.Transform(ColumnNames, ProfileColumn)
+    )
+in
+    Profile
+```
+
+### Profile Results Interpretation
+
+```
+DATA PROFILE RESULTS
+====================
+
+Table: FactSales
+Rows: 1,245,678
+
+| Column | Non-Null % | Unique % | Issue |
+|--------|------------|----------|-------|
+| SalesKey | 100% | 100% | ✅ OK (PK) |
+| DateKey | 100% | 0.08% | ✅ OK |
+| CustomerKey | 98.5% | 2.1% | ⚠️ 1.5% null |
+| Amount | 99.9% | 15.2% | ✅ OK |
+| Discount | 45.2% | 3.1% | ⚠️ 55% null (expected?) |
+| Region | 100% | 0.0004% | ✅ OK (4 regions) |
+
+FINDINGS:
+1. CustomerKey has 18,685 null values
+   - Are anonymous sales valid?
+   - Should map to "Unknown Customer"?
+
+2. Discount is mostly null
+   - Normal if most sales have no discount
+   - Consider: null vs 0 distinction?
+
+Would you like to:
+1. Define validation rules for issues found
+2. Profile another table
+3. Create cleaning steps
+```
+
+---
+
+## PHASE 2: Validation Rules
+
+```
+VALIDATION RULE BUILDER
+=======================
+
+Let's define rules for your data. Common rule types:
+
+1. NOT NULL - Column must have a value
+2. UNIQUE - No duplicate values allowed
+3. REFERENTIAL - Must exist in another table
+4. RANGE - Value must be within min/max
+5. PATTERN - Must match regex (email, phone, ID)
+6. BUSINESS - Custom logic (Amount > 0, Date < Today)
+
+Which column would you like to add rules for?
+```
+
+### Power Query Validation Layer
+
+```powerquery
+// Validation Layer
+// Add after source, before other transformations
+
+let
+    Source = PreviousStep,
+
+    // === VALIDATION RULES ===
+
+    // Rule 1: CustomerKey not null (map nulls for tracking)
+    #"Validate CustomerKey" = Table.AddColumn(
+        Source,
+        "_Val_CustomerKey",
+        each if [CustomerKey] = null then "NULL_VALUE" else "OK"
+    ),
+
+    // Rule 2: Amount must be >= 0
+    #"Validate Amount" = Table.AddColumn(
+        #"Validate CustomerKey",
+        "_Val_Amount",
+        each if [Amount] = null then "NULL_VALUE"
+             else if [Amount] < 0 then "NEGATIVE_VALUE"
+             else "OK"
+    ),
+
+    // Rule 3: Date must be within expected range
+    #"Validate Date" = Table.AddColumn(
+        #"Validate Amount",
+        "_Val_Date",
+        each if [OrderDate] = null then "NULL_VALUE"
+             else if [OrderDate] > DateTime.LocalNow() then "FUTURE_DATE"
+             else if [OrderDate] < #date(2020, 1, 1) then "DATE_TOO_OLD"
+             else "OK"
+    ),
+
+    // Rule 4: Email format validation
+    #"Validate Email" = Table.AddColumn(
+        #"Validate Date",
+        "_Val_Email",
+        each if [Email] = null then "NULL_VALUE"
+             else if not Text.Contains([Email], "@") then "INVALID_FORMAT"
+             else "OK"
+    ),
+
+    // === COMBINE VALIDATION RESULTS ===
+
+    #"Add Overall Status" = Table.AddColumn(
+        #"Validate Email",
+        "_ValidationStatus",
+        each if List.ContainsAny(
+            {[_Val_CustomerKey], [_Val_Amount], [_Val_Date], [_Val_Email]},
+            {"NULL_VALUE", "NEGATIVE_VALUE", "FUTURE_DATE", "DATE_TOO_OLD", "INVALID_FORMAT"}
+        ) then "FAILED" else "PASSED"
+    ),
+
+    // === SEPARATE VALID AND INVALID ===
+
+    // Option A: Keep all records with validation columns
+    AllRecords = #"Add Overall Status",
+
+    // Option B: Split into valid/invalid tables
+    ValidRecords = Table.SelectRows(
+        AllRecords,
+        each [_ValidationStatus] = "PASSED"
+    ),
+
+    InvalidRecords = Table.SelectRows(
+        AllRecords,
+        each [_ValidationStatus] = "FAILED"
+    )
+
+in
+    ValidRecords  // Change to InvalidRecords to see errors
+```
+
+### Validation Functions Library
+
+```powerquery
+// Reusable validation functions
+// Add as a separate query named "fnValidation"
+
+let
+    // Check if value is null or empty
+    fnIsNullOrEmpty = (value) =>
+        value = null or (Value.Is(value, type text) and Text.Trim(value) = ""),
+
+    // Check email format
+    fnIsValidEmail = (email) =>
+        email <> null and
+        Text.Contains(email, "@") and
+        Text.Contains(email, ".") and
+        Text.Length(email) > 5,
+
+    // Check date is within range
+    fnIsValidDate = (date, minDate, maxDate) =>
+        date <> null and
+        date >= minDate and
+        date <= maxDate,
+
+    // Check numeric range
+    fnIsInRange = (value, minVal, maxVal) =>
+        value <> null and
+        value >= minVal and
+        value <= maxVal,
+
+    // Check for duplicates in a list
+    fnHasDuplicates = (list) =>
+        List.Count(list) <> List.Count(List.Distinct(list)),
+
+    // Combined validation result
+    fnValidateRecord = (record, rules) =>
+        let
+            Results = List.Transform(rules, each _(record)),
+            HasErrors = List.ContainsAny(Results, {false})
+        in
+        if HasErrors then "FAILED" else "PASSED"
+in
+    [
+        IsNullOrEmpty = fnIsNullOrEmpty,
+        IsValidEmail = fnIsValidEmail,
+        IsValidDate = fnIsValidDate,
+        IsInRange = fnIsInRange,
+        HasDuplicates = fnHasDuplicates,
+        ValidateRecord = fnValidateRecord
+    ]
+```
+
+---
+
+## PHASE 3: DAX Monitoring Measures
+
+```
+DATA QUALITY MONITORING MEASURES
+================================
+
+Add these measures to track quality over time:
+```
+
+### Completeness Measures
+
+```dax
+// Count null values in key column
+DQ_CustomerKey_NullCount =
+CALCULATE(
+    COUNTROWS(FactSales),
+    ISBLANK(FactSales[CustomerKey])
+)
+
+// Percentage of nulls
+DQ_CustomerKey_NullPct =
+DIVIDE(
+    [DQ_CustomerKey_NullCount],
+    COUNTROWS(FactSales),
+    0
+)
+
+// Completeness score (% non-null)
+DQ_CustomerKey_Completeness =
+1 - [DQ_CustomerKey_NullPct]
+```
+
+### Validity Measures
+
+```dax
+// Count records with negative amounts
+DQ_Amount_NegativeCount =
+CALCULATE(
+    COUNTROWS(FactSales),
+    FactSales[Amount] < 0
+)
+
+// Count future dates (data entry errors)
+DQ_Date_FutureCount =
+CALCULATE(
+    COUNTROWS(FactSales),
+    FactSales[OrderDate] > TODAY()
+)
+
+// Count invalid emails
+DQ_Email_InvalidCount =
+CALCULATE(
+    COUNTROWS(DimCustomer),
+    NOT(CONTAINSSTRING(DimCustomer[Email], "@"))
+)
+```
+
+### Uniqueness Measures
+
+```dax
+// Count duplicate orders (should be 0)
+DQ_DuplicateOrders =
+VAR _TotalRows = COUNTROWS(FactSales)
+VAR _UniqueOrders = DISTINCTCOUNT(FactSales[OrderID])
+RETURN _TotalRows - _UniqueOrders
+```
+
+### Referential Integrity Measures
+
+```dax
+// Count orphan records (no matching customer)
+DQ_Orphan_Customers =
+CALCULATE(
+    DISTINCTCOUNT(FactSales[CustomerKey]),
+    ISBLANK(RELATED(DimCustomer[CustomerName]))
+)
+
+// Percentage of orphan records
+DQ_Orphan_Customers_Pct =
+DIVIDE(
+    [DQ_Orphan_Customers],
+    DISTINCTCOUNT(FactSales[CustomerKey]),
+    0
+)
+```
+
+### Overall Quality Score
+
+```dax
+// Combined quality score (0-100)
+DQ_OverallScore =
+VAR _TotalChecks = 5
+VAR _PassedChecks =
+    ([DQ_CustomerKey_NullPct] <= 0.01) +         // Max 1% nulls
+    ([DQ_Amount_NegativeCount] = 0) +             // No negatives
+    ([DQ_Date_FutureCount] = 0) +                 // No future dates
+    ([DQ_DuplicateOrders] = 0) +                  // No duplicates
+    ([DQ_Orphan_Customers] = 0)                   // No orphans
+RETURN
+    DIVIDE(_PassedChecks, _TotalChecks) * 100
+
+// Quality status text
+DQ_Status =
+SWITCH(
+    TRUE(),
+    [DQ_OverallScore] >= 95, "✅ Excellent",
+    [DQ_OverallScore] >= 80, "🟡 Good",
+    [DQ_OverallScore] >= 60, "🟠 Needs Attention",
+    "🔴 Critical Issues"
+)
+```
+
+---
+
+## PHASE 4: Data Quality Dashboard
+
+```
+DATA QUALITY DASHBOARD
+======================
+
+Recommended layout for monitoring:
+
+┌─────────────────────────────────────────────────────┐
+│              DATA QUALITY SCORECARD                  │
+│                                                     │
+│    Overall Score: 94%    Status: 🟡 Good           │
+│    Last Refresh: Today 08:15 AM                    │
+├─────────────────────────────────────────────────────┤
+│  Completeness  │  Validity   │  Uniqueness         │
+│     98.5%      │    99.2%    │    100%            │
+├─────────────────────────────────────────────────────┤
+│              ISSUES REQUIRING ATTENTION             │
+│                                                     │
+│  ⚠️ 1,234 records with null CustomerKey           │
+│  ⚠️ 56 negative Amount values                     │
+│  ⚠️ 12 future dates detected                      │
+│                                                     │
+├─────────────────────────────────────────────────────┤
+│              QUALITY TREND (30 DAYS)               │
+│                                                     │
+│  [Line chart: Score over time]                     │
+│                                                     │
+├─────────────────────────────────────────────────────┤
+│              ISSUE BREAKDOWN BY TABLE              │
+│                                                     │
+│  [Bar chart: Issues per table]                     │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+
+Would you like me to help you build this dashboard?
+```
+
+---
+
+## COMMON VALIDATION PATTERNS
+
+### Date Validations
+
+```powerquery
+// Date is not in the future
+each [Date] <= DateTime.LocalNow()
+
+// Date is within fiscal year
+each [Date] >= #date(2024, 1, 1) and [Date] <= #date(2024, 12, 31)
+
+// Date is a weekday
+each Date.DayOfWeek([Date]) <> Day.Saturday and
+     Date.DayOfWeek([Date]) <> Day.Sunday
+```
+
+### Numeric Validations
+
+```powerquery
+// Positive amount
+each [Amount] > 0
+
+// Percentage between 0 and 100
+each [Percentage] >= 0 and [Percentage] <= 100
+
+// Quantity is whole number
+each Number.RoundDown([Quantity]) = [Quantity]
+```
+
+### Text Validations
+
+```powerquery
+// Not empty or whitespace
+each Text.Trim([Name]) <> ""
+
+// Minimum length
+each Text.Length([Code]) >= 5
+
+// Matches pattern (simple)
+each Text.StartsWith([SKU], "SKU-")
+
+// Email format (basic)
+each Text.Contains([Email], "@") and Text.Contains([Email], ".")
+```
+
+### Referential Integrity
+
+```powerquery
+// Check if key exists in lookup table
+let
+    ValidKeys = List.Buffer(Table.Column(DimProduct, "ProductKey"))
+in
+    each List.Contains(ValidKeys, [ProductKey])
+```
+
+---
+
+## ERROR HANDLING STRATEGIES
+
+### Strategy 1: Replace with Default
+
+```powerquery
+// Replace nulls with default value
+= Table.ReplaceValue(
+    Source,
+    null,
+    -1,  // or "Unknown", 0, etc.
+    Replacer.ReplaceValue,
+    {"CustomerKey"}
+)
+```
+
+### Strategy 2: Remove Invalid Rows
+
+```powerquery
+// Remove rows that fail validation
+= Table.SelectRows(
+    Source,
+    each [_ValidationStatus] = "PASSED"
+)
+```
+
+### Strategy 3: Route to Error Table
+
+```powerquery
+// Create separate error output
+let
+    Errors = Table.SelectRows(Source, each [_ValidationStatus] = "FAILED"),
+    // Add error timestamp and details
+    WithTimestamp = Table.AddColumn(Errors, "ErrorDate", each DateTime.LocalNow()),
+    WithDetails = Table.AddColumn(WithTimestamp, "ErrorDetails",
+        each Text.Combine(
+            List.Select(
+                {[_Val_CustomerKey], [_Val_Amount], [_Val_Date]},
+                each _ <> "OK"
+            ),
+            "; "
+        )
+    )
+in
+    WithDetails
+```
+
+### Strategy 4: Flag and Continue
+
+```powerquery
+// Keep all records but flag issues
+= Table.AddColumn(
+    Source,
+    "DataQualityFlag",
+    each if [_ValidationStatus] = "FAILED" then "Review Required" else "Clean"
+)
+```
+
+---
+
+## BEST PRACTICES
+
+### Do's
+
+| Practice | Reason |
+|----------|--------|
+| Profile before cleaning | Understand data first |
+| Document all rules | Traceability and maintenance |
+| Keep error logs | Audit trail for data issues |
+| Monitor trends | Catch degradation early |
+| Test with edge cases | Ensure rules work correctly |
+| Use consistent naming | _Val_, DQ_ prefixes |
+
+### Don'ts
+
+| Anti-Pattern | Problem |
+|--------------|---------|
+| Silent fixes | Hides data issues from business |
+| Overly strict rules | Rejects valid edge cases |
+| Validation in DAX only | Too late in pipeline |
+| No error handling | Query failures crash reports |
+| Ignoring nulls | Can cause wrong calculations |
+
+---
+
+## DATA QUALITY REPORT TEMPLATE
+
+```markdown
+# Data Quality Report
+Generated: [Date]
+Model: [Name]
+Period: [Start Date] - [End Date]
+
+## Executive Summary
+- Overall Quality Score: [X]%
+- Critical Issues: [X]
+- Warnings: [X]
+- Tables Analyzed: [X]
+
+## Detailed Findings
+
+### Table: FactSales
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| Completeness | 98.5% | > 95% | ✅ Pass |
+| Validity | 99.2% | > 99% | ✅ Pass |
+| Uniqueness | 100% | = 100% | ✅ Pass |
+
+Issues:
+1. 1,234 null CustomerKey values
+   - Impact: Cannot link to customer dimension
+   - Recommendation: Map to "Unknown Customer"
+
+### Table: DimCustomer
+[Similar structure]
+
+## Trend Analysis
+[Quality score over last 30 days]
+
+## Recommendations
+1. [High Priority] Fix CustomerKey nulls
+2. [Medium] Add validation for Amount range
+3. [Low] Consider data cleansing for legacy records
+
+## Next Review Date: [Date]
+```
+
+---
+
+## 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
+
+- `/power-query` — Fix data issues in transformations
+- `/testing-validation` — Automated data tests
+- `/governance` — Data quality standards
+
+---
+
+## RELATED RESOURCES
+
+- [Power Query Patterns](../power-query/SKILL.md)
+- [DAX Best Practices](../dax/SKILL.md)
+- [Data Modeling](../data-modeling/SKILL.md)