/organize-semantic-model

name: organize-semantic-model
description: Organize a Power BI or Analysis Services semantic model end to end so it is ready for report authors, Excel users and Copilot - table groups, display folders, Title Case business names and naming conventions, hierarchies, sort-by columns, hiding, Analyze in Excel (IsAvailableInMDX), descriptions, format strings, data categories, context annotations, DAX formatting and UDFs, calculated-object justification, duplicate removal, perspectives, translations and security roles. Use whenever the user asks to "organize", "tidy", "clean up", "polish", "prepare", "standardize" or "make report-ready" a model or one table in it (for example "organize the date table"), to "fix naming conventions", "rename fields", "make names human readable" or "fix abbreviations", even when they name only one of these aspects, and whenever a model is driven through the Tabular Editor 3 MCP or the te CLI for that purpose. Not for DAX performance tuning (dax skill) or model design and star-schema changes (semantic-model skill).

Organize a semantic model

[Workflow] Organizing is a set of passes over the same objects. Doing only one or two of them (folders and sorting, say) leaves the model looking finished while names, descriptions and formats are still raw, so run every pass unless the user narrows the scope, and say which passes were skipped and why.

Tooling

• Tabular Editor 3 MCP: call `get_workspace_info` first and confirm the model title with the user if it is not the one they named. Read with `get_model_overview` and `get_object_details`; write with `execute_csharp_script`
• `te` CLI (the `te-cli` skill) when there is no TE3 instance, for example against PBIP/TMDL on disk
• One script per pass. Each `execute_csharp_script` call is one undo step and returns a property-level diff, so per-pass scripts keep every change reviewable and individually revertible
• Read the returned diff after every script. Confirm each property you meant to set appears, and nothing you did not mean to touch. A property missing from the diff was already at that value, except annotations: the diff does not list annotation changes (`TableGroup`, `context`), so read those back with a second script
• `execute_dax_query` only exists while the TE3 MCP server has model data read permission. If it disappears mid-session, the client's tool list is stale; reconnect the server (`/mcp`). A calculated table that was never recalculated returns no data until it is refreshed
• Ask the user to close TE3 DAX editor tabs for objects a script will change. A script that edits an object while its editor is open and parsing has crashed TE3 (`IndexOutOfRangeException` in `ScrollbarIndicatorsController`)
• Nothing is saved or deployed by the MCP. On a live connection, saving writes to the server, so leave saving to the user

Pass 0: inventory and lineage

Before changing anything:

1. Record the starting state: tables, columns, measures, functions, existing display folders, table groups, hierarchies, cultures, perspectives, roles and annotations 2. Find downstream consumers with the `lineage-analysis` skill (or `fab` through the `fabric-cli` skill): reports bound to the model in every workspace, and composite models on top of it. Renames, deletions and the Analyze in Excel pass all depend on this 3. Note the cultures. Some TE operations write translated captions automatically (adding a hierarchy does), and renames leave existing translations pointing at the new object

Pass 1: table groups and display folders

• Table groups: set `table.TableGroup` (stored as the `TabularEditor_TableGroup` annotation). Use role-based groups such as `Facts`, `Dimensions`, `Measures`, `Calculation Groups`, `Parameters`. Groups only show in Tabular Editor; they do not reach Power BI, which is why table names must not carry `DIM_`/`FACT_` prefixes instead
• Display folders: put every visible column and measure in a folder. Aim for 3 to 5 top-level folders per table. More than 5 means the table mixes subjects or the folders are too fine. Keep a larger existing structure if it predates the session; do not flatten the user's own work
• Nest with `/` only (`Keys/Technical`); one level is usually enough
• Folders on hidden objects are invisible to users. Set them so a later unhide lands somewhere sensible, but do not spend top-level folders on them

Pass 2: names

Title Case business names for tables, columns, measures and hierarchies (`Order Date`, `Net Sales`, `Days of Supply`), acronyms in capitals, no programming conventions, no technical prefixes, no unexplained abbreviations, and one consistent syntax for aggregations, units, periods and comparisons. The full rule set, the measure name construction order and the terminology questions to ask first are in `references/naming-rules.md`.

• Conformed nomenclature: one concept, one word, everywhere. `Customer Key`, `Customer`, `Cust` for the same thing across tables collapse to one form; qualifiers that carry meaning (`Billing Date`, `Order Date`) stay. Pick singular or plural table names once
• Calculated table columns bind to the expression's output through `SourceColumn`. Renaming the column object is enough while `SourceColumn` still matches an expression column; when the expression's names change, keep `SourceColumn` in step or the column is dropped on recalculation
• Renaming in Tabular Editor carries relationships, sort-by columns, hierarchy levels, translations and perspective membership along, and renames a calculated table's partition with the table
• Before renaming, show the user the old-to-new map and warn that renames break report visuals, filters, bookmarks and field parameters bound to the old names. Pass 0 found the consumers; offer to rebind them with the `pbir-cli` skill (local PBIR) or `fabric-cli` (service). Do not apply renames to a model with bound reports without that go-ahead. `refactoring-renaming.md` in the `semantic-model` skill has the full pr