bpa-rules

# Best Practice Analyzer Rules

Expert guidance for creating and improving BPA (Best Practice Analyzer) rules for Tabular Editor and Power BI semantic models.

## When to Use This Skill

Activate automatically when tasks involve:

- Creating new BPA rules for semantic model validation
- Recommending or choosing BPA rules for a model, team, or organization
- Improving or debugging BPA rule expressions
- Writing FixExpression to auto-remediate rule violations
- Understanding BPA annotations in TMDL files
- Analyzing a semantic model against best practices
- Converting ad-hoc checks into reusable BPA rules
- Auditing or discovering all BPA rules across sources (built-in, URL, model, user, machine)

## Primary Workflow: Interactive Q&A Discovery (Double Diamond)

**CRITICAL: Do NOT generate BPA rules immediately.** This is a requirements-gathering exercise. Use the `AskUserQuestion` tool to conduct an iterative, back-and-forth conversation with the user across multiple rounds. Continue asking questions until sufficient context about the user's business, team, model, and priorities has been gathered. Only then move to rule generation.

The workflow follows a **double-diamond** pattern:
1. **Diverge** -- broadly explore the user's context, organization, and goals
2. **Converge** -- narrow down to specific priorities and constraints
3. **Diverge** -- explore the model structure and identify candidate rule areas
4. **Converge** -- select and generate the final tailored rule set

### Diamond 1: Requirements Gathering (Phases 1-2)

#### Phase 1: Understand the User and Organization

Call `AskUserQuestion` with 2-4 questions per round. After each round, review the answers and ask follow-up questions. **Do not proceed to Phase 2 until the organizational context is clear.** Continue rounds until satisfied.

**Round 1 -- Goal and audience:**

Ask about the primary goal and who will use the rules. Example AskUserQuestion call:
- Question 1: "What is the primary goal for these BPA rules?" -- options: "Set up BPA for my team", "Improve a specific model", "Create governance/compliance rules", (Other)
- Question 2: "Who will use these rules?" -- options: "Solo developer", "Small team (2-5)", "Large org / multiple teams", (Other)
- Question 3: "What tooling do you use?" -- options: "Tabular Editor 3", "Tabular Editor 2", "TE CLI in CI/CD", "Fabric notebooks"

**Round 2 -- Standards and existing rules:**

Based on Round 1 answers, ask about conventions and existing rules. Example:
- Question 1: "Do you have existing naming conventions?" -- options: "Yes, documented", "Yes, informal/ad-hoc", "No conventions yet", (Other)
- Question 2: "Are there BPA rules already in use?" -- options: "Yes, in Tabular Editor", "Yes, from a URL/repo", "No existing rules", (Other)
- Question 3: "Which categories matter most?" -- multiSelect: true -- options: "Performance", "Metadata/Documentation", "DAX quality", "Naming conventions"

**Round 3+ -- Follow-ups as needed:**

If the user has existing rules, ask for the file path or URL and read them. If they have naming conventions, ask for specifics. If they mentioned CI/CD, ask about the pipeline setup. **Keep calling AskUserQuestion until the organizational picture is clear.**

#### Phase 2: Investigate the Model

After Phase 1, use `AskUserQuestion` to determine how to access the model:

- Question: "How is your semantic model available?" -- options: "Published to Fabric / Power BI Service", "Local as PBIP (.tmdl files)", "Local as .pbix file", "I have a model.bim file"

**Then investigate the model based on the answer:**

| Answer | Action |
|--------|--------|
| **Published to Fabric** | Use `AskUserQuestion` to get workspace and model name. Then use `fab` CLI to inspect remotely -- load the `fabric-cli` skill and read `references/model-investigation.md` for specific commands. |
| **Local as PBIP** | Use `AskUserQuestion` to get the path to the `.SemanticModel/definition/` folder. Then read TMDL files directly with Read/Grep tools. |
| **Local as .pbix only** | Guide the user to save as PBIP: **File > Save as > Power BI Project (*.pbip)** in Power BI Desktop. Then ask for the resulting folder path. See `references/model-investigation.md` for detailed steps. |
| **model.bim file** | Use `AskUserQuestion` to get the file path. Then parse with `jq` or read directly. |
| **No model yet** | Skip model investigation; generate general-purpose rules based on organizational context only. |

**What to extract from the model** (read files, grep patterns, count objects):
- Table count, measure count, column count
- Storage mode (Import, DirectQuery, Direct Lake, mixed)
- Metadata completeness (descriptions, display folders, format strings)
- DAX patterns in use (CALCULATE, FILTER/ALL, calculation groups, UDFs)
- Relationship patterns (bi-directional, many-to-many, inactive)
- RLS roles defined
- Naming conventions currently in use
- Existing BPA annotations already embedded in model.tmdl

After model investigation, **summarize findings to the user** and use `AskUserQuestion` to confirm the analysis is accurate and ask if anything was missed.

### Diamond 2: Rule Generation (Phases 3-4)

#### Phase 3: Prioritize and Recommend

Based on everything gathered, present a prioritized recommendation of rule categories. Use `AskUserQuestion` to let the user confirm or adjust before generating any rules.

**Present categories ranked by relevance to the user's context.** For example:

If the model has many measures without descriptions and the user cares about governance:
1. Metadata (high priority -- many objects lack descriptions)
2. Governance (high priority -- user goal)
3. Performance (medium -- some unused hidden columns detected)
4. DAX Expressions (medium -- some FILTER/ALL patterns found)
5. Naming Conventions (low -- model already follows consistent naming)

Use `AskUserQuestion` to ask:
- Which categories to include (multiSelect)
- What severity level to assign to each category (or let