| name | mcp-engine-refactoring |
| description | Use when renaming, consolidating, restructuring, or batch-editing Power BI model objects that have downstream consumers — measure consolidation, table or column renames, splitting a flat table toward a star schema, moving repeated logic into calculation groups, or executing a model-quality remediation backlog. For a single-object edit with no consumers, use mcp-engine-schema-authoring or mcp-engine-semantic-authoring directly. |
PBI Refactoring
Safe multi-object change orchestration: dependencies, baselines, checkpoints, staged edits, verification, rollback. The phases and their order live in refactoring-workflow — follow it phase by phase; do not edit before its phases 1-4 are complete.
Workflow
- Scope — object list and change class, confirmed with
list_model { "operation": "list", "spec": { "type": "<type>" } } / { "operation": "search", "spec": { "query": "<name>", "mode": "name" } }.
- Baseline — 3-5 representative
run_query { "operation": "execute", "query": "<aggregate>" } calls recorded verbatim, or durable manage_tests regression_snapshot / measure_assertion tests that pass before any edit.
- Impact —
manage_dependencies { "operation": "used_by", "spec": { "target": { "type": "<type>", "table": "<table>", "name": "<name>" } } } per object (spec.target is required on every call) plus list_model expression search (mode: "dax" and "m"), repeated until no new consumers appear; blast radius reported to the user first.
- Safety net —
manage_model_changes { "operation": "pin_checkpoint", "name": "before-<goal>" }; multi-object edits staged as a named changeset (create_changeset returns the changeset_id that add_to_changeset, preview_changeset, and apply_changeset require).
- Execute in order — create replacements → update consumers → rename or delete originals;
dry_run: true on the first attempt of each operation shape.
- Verify — baselines re-run and compared exactly;
diff_transaction (with the transaction_id from list_transactions) reviewed against the plan; old names searched one final time.
- Decide — keep, or
rollback_transaction / restore_checkpoint on any unintended mismatch.
Recipes for the common cases (rename with consumers, measure consolidation, calc-group relocation, hygiene sweep) are in the workflow guide.
Guardrails
- One refactor goal per run; never mix renames with logic changes.
- Dependency analysis cannot see report visuals or external consumers that bind by name — warn the user on every rename of a visible object.
- An intended value change discovered mid-refactor must be confirmed by the user, never silently absorbed.
- The actual edits follow the authoring guides of
mcp-engine-schema-authoring and mcp-engine-semantic-authoring; this skill owns the sequence around them. If those skills are not installed, make the edits from the tools' inputSchema or ask the user to add them.
Report results
After a refactor, report:
- Scope, change class, and final consumer count per object.
- Checkpoint and changeset ids created.
- Each edit applied, in order.
- Baseline comparison outcome: identical, intended differences confirmed, or rolled back.
- Remaining risks (report-layer renames, deferred deletions) and the rollback point still available.
References
