# Powerbi Report Planning > Build a guided requirements-to-implementation workflow for new Power BI reports and dashboards from semantic models, datasets, or PBIP projects. Use when the user wants to: (1) plan then implement a report, (2) define audience, scope, page plan, design direction, dependencies, and delivery target, (3) create a locked report spec with approval before PBIR authoring. For direct edits to existing report files, use `powerbi-report-authoring`. For design-only critique or redesign, use `powerbi-report-design`. Triggers: "build me a dashboard", "create a new report", "plan then implement", "define and build Power BI report", "walk me through creating a report". - Skill: `microsoft/powerbi-report-planning` (Agent Skill) - Install (CLI): `npx skillmds@latest add microsoft/powerbi-report-planning` - Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/powerbi-report-planning/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: Microsoft (https://skillmd.com/u/microsoft) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/microsoft/powerbi-report-planning --- # Power BI Report Planning Skill This skill orchestrates the full lifecycle for a new Power BI report: **Define -> Inspect -> Spec -> Approve -> Build -> Validate -> Publish** It is intentionally broader than a pure requirements-gathering flow: it captures the report spec **and** continues into implementation after the user approves. ## Must/Prefer/Avoid ### MUST - Use this skill for broad report creation workflows that need requirements, dependency checks, approval, and build sequencing. - Ask focused clarification questions one at a time and stop after the required decision is clear. - Lock `_brief/report-spec.md` and get approval before implementation. - Route design decisions through `powerbi-report-design` and file mechanics through `powerbi-report-authoring`. ### PREFER - Infer obvious answers from the prompt, model, existing PBIP files, or earlier rounds instead of re-asking. - Inspect the semantic model before finalizing page scope or visual recommendations. - Treat publishing as optional and only proceed when approved. ### AVOID - Do not use this skill for small, surgical edits to existing PBIR files. - Do not build before the user approves the locked report spec. - Do not duplicate detailed visual-design or PBIR-authoring guidance that belongs to companion skills. ## Examples of When to Use Use this skill when the user wants to create a new Power BI report and needs both: 1. A guided requirements workflow. 2. A path to implementation after approval. Examples: - "Let's create a new Power BI report from this semantic model." - "Help me define and then build a Power BI report." - "Use the report playbook to start a new report." - "Create a reusable workflow for new Power BI reports." Do **not** use this skill for a small edit to an existing report page. For direct PBIR authoring tasks, use `powerbi-report-authoring`. For visual critique or greenfield design guidance **without the full guided workflow** (a one-off "redesign this" or "what should this look like?"), use `powerbi-report-design` directly. This skill *uses* the design skill during Rounds 3–4 — it does not replace it. ## Required Operating Rules 1. **Ask one question at a time.** Use `ask_user` for each clarification. 2. **Run 3-5 clarification rounds maximum.** Each round may have one primary question and, only if absolutely necessary, one follow-up. 3. **Inspect the semantic model before locking the spec.** Use the semantic model skill or an MCP server when available; otherwise inspect local TMDL/PBIP files directly. 4. **Check dependencies explicitly.** Do not assume Desktop, MCP, authoring, or Fabric publishing are available. 5. **Produce one locked `_brief/report-spec.md` before building.** 6. **Ask for approval before implementation.** Do not build until the user explicitly approves. 7. **When approved, build end-to-end.** Model changes, PBIR generation, validation, Desktop preview, screenshot loop, and optional Fabric publish. 8. **Local edits stay local unless publishing is approved.** 9. **Do not re-ask known answers.** If the original prompt, inspected files, or a prior round already provides audience, page count, delivery target, scope, or design direction, capture it in working notes and move on. Ask only for genuine ambiguity or risky tradeoffs. ## Dependency Checklist Before implementation, capture this status: | Dependency | Purpose | Required When | |---|---|---| | Power BI Desktop | Open/reload PBIP and visually validate report | Always for local preview | | PBIP/PBIR project | File-based report authoring | Always for generated reports | | TMDL semantic model | Model persistence and source control | Required for model edits | | `powerbi-modeling-mcp` | Inspect tables, columns, measures; create measures/columns; deploy semantic model | Required for live model authoring | | `powerbi-report-authoring` skill | Validate PBIR, reload Desktop, screenshot pages | Required for report authoring validation | | `powerbi-report-management` skill | Create/update/download Fabric reports | Required only for Fabric publishing | | Node.js | Generator-based PBIR authoring | Recommended for reproducible reports | If a dependency is unavailable, continue planning and mark the affected phase as blocked/manual. Do not pretend it is available. ## Round Structure ### Round 0 — Setup and Dependency Check Goal: identify the semantic model, report target, and available tooling. Ask only what cannot be inspected automatically: > What semantic model or dataset should this report use? Recommended choices should be concrete if candidates are discoverable. Enumerate existing Fabric semantic models and local `.SemanticModel` folders in scope, then present them as options and mark the best match as recommended. Example: - `` (Recommended) - Another existing Fabric semantic model - A new local dataset Then inspect/check: - Existing `.pbip`, `.Report`, `.SemanticModel` folders. - Whether TMDL files exist. - Whether Power BI Desktop automation script exists. - Whether MCP connection is available or can be established. - Whether Fabric publishing is requested. Output working notes: ```markdown Dependency status: - Semantic model: - PBIP/PBIR: - Desktop preview: - Modeling MCP: - Report-authoring skill: - Fabric publishing: - Node generator: ``` ### Round 1 — Audience and Job Goal: understand who the report is for and what decision/job it supports. If both audience and job-to-be-done are already clear from the prompt, summarize the inferred answer instead of asking. Otherwise ask for the missing piece(s), one at a time. Ask when audience is unclear: > Who is this report primarily for? Recommended choices: 1. Executives / leadership — concise KPIs, trends, risks, decisions 2. Analysts — exploration, drilldowns, comparisons, tables 3. Operators — monitoring, exceptions, status, action queues 4. External audience — polished story, guided narrative, minimal slicers 5. Enthusiasts / fans — magazine-style narrative, rich visuals, rankings Then ask only if the job-to-be-done is still unclear: > What should the report help them do? Recommended choices: 1. Understand the overall story 2. Track performance 3. Find outliers or opportunities 4. Compare entities or segments 5. Explore individual records/profiles 6. Prepare for a recurring business review Capture: ```markdown Audience: Primary purpose: Tone: Success criteria: ``` ### Round 2 — Model Inventory and Scope Goal: inspect the model and define the first-build scope boundary without re-asking for scope the user already gave. Use whatever model-inspection capability is available — pick the first that applies, in order of preference: 1. A semantic-model authoring skill, if installed. 2. A modeling MCP server (e.g., `powerbi-modeling-mcp-*`) — connect to the live model, list tables/columns/measures/relationships, and run DAX for live validation. 3. Direct reads of local TMDL files (`definition/model.tmdl`, `definition/tables/*.tmdl`, `definition/relationships.tmdl`) when no live connection is available. Do not hardcode tool names in user-facing prompts — describe the inspection intent and let the agent pick the available tool. Summarize: ```markdown Facts: - table, grain, keys, useful measures Dimensions: - date/time, geography, entity, category, owner, status, segment Existing measures: - core available measures Likely missing model work: - measures - calculated columns - relationship fixes - sort columns - helper fields for slicers/search Risks: - nulls/sparsity - inactive relationships - high-cardinality slicers - fields that will not filter as expected ``` After inspection, infer the first-build scope from the original request and prior answers. Do not ask a standalone scope question if the user already gave a page count, report type, or content boundary (for example, "build a 4 page dashboard"). Instead, summarize the boundary in working notes: ```markdown First-build scope: - - inferred from: - included now: - deferred: ``` Ask a scope question only when the boundary is unclear, too broad, or risky. If asking, present tailored choices from the inspected model rather than generic first-build options. Example: > The model supports sales, products, geography, discounts, and profitability. > For this first build, should we keep it focused on executive performance, or > include a deeper product/customer exploration too? ### Round 3 — Narrative and Page Plan Goal: turn the model and scope into page architecture. Invoke or explicitly consult `powerbi-report-design` for page-level archetype routing and composition guidance. The design skill owns visual routing; do not duplicate its routing table here. Use the data shape from Round 2 to surface 2-3 report shape options for user sign-off. The five archetypes the design skill ships are: **Executive Summary**, **Operational Monitor**, **Analytical Canvas**, **Narrative Story**, **Comparative Benchmark**. Use the design skill's archetype and composition guidance for layout variants, multi-archetype reports, and cross-page variant rotation. Ask only after applying the inferred first-build scope from Round 2: > Which report shape should we use? Present 2–3 named compositions (e.g., *Executive landing + Analytical exploration + Comparative ranking* for a multi-domain ask, or *Single executive landing* for a focused ask). Recommend one based on Rounds 1–2 and mark it `(Recommended)`. Draft page list in the answer after the user chooses: ```markdown Proposed pages: 1. — archetype — purpose — core visuals — fields/measures 2. — archetype — purpose — core visuals — fields/measures ``` Capture slicers and interactions: - Global slicers - Page-specific slicers - Search/prefix slicers for high-cardinality dimensions - Drillthrough/profile pages - Bookmarks/navigation if needed ### Round 4 — Design Identity, Accessibility, and Delivery Goal: lock the design identity, accessibility baseline, and delivery target. Invoke or explicitly consult `powerbi-report-design` for design identity and theme direction. Design identity (tone + signature) is owned by the design skill — do not invent a parallel vocabulary here. Use the design skill's identity guidance to pick a tone+signature combination, then surface it to the user. Ask: > What should this report feel like? Present 2–3 concrete identity options adapted to the audience and domain from Rounds 1–2. Each option names a report feel and the one signature visual move it implies. Recommend one and mark it `(Recommended)`. If the user has brand guidelines, make one option brand-forward rather than picking a generic tone. Then ask delivery only if unclear: > Where should the finished report end up? Recommended choices: 1. Local PBIP only first 2. Publish to an existing Fabric workspace 3. Create new semantic model + report in Fabric 4. Update an existing Fabric report 5. Build local first, decide publishing later Design defaults (these come from the design skill's gotchas + base theme; applied automatically unless the user overrides): - Use accessible contrast (WCAG AA minimum on every text/background pair). - Avoid red-on-red and low-contrast palettes. - Prefer Azure Map over deprecated map/filledMap visuals. - Add alt text to every chart. - Use searchable dropdown slicers for high-cardinality fields. - Use tile/list slicers only for short categorical fields. - Place detailed tables near the bottom of the page. - Keep report interactions predictable and consistent. ## Design Contract Gate Before producing `_brief/report-spec.md` for approval, get a canonical `Design Brief:` YAML block from `powerbi-report-design`. The planner may provide requirements, model inventory, page goals, and user constraints to the design skill, but the planner must not author a competing detailed design skeleton. The canonical design block must include: - `generated_by: powerbi-report-design` - `contract_version` - one `pages[]` entry for every page in the page plan - `pages[].layout_contract.canvas` - `pages[].layout_contract.grid.regions` - `pages[].layout_contract.placements` - `pages[].layout_contract.space_audit` - one `page_title` textbox placement with non-empty title text per page - slicer placements in a top-right `filters` region or a justified filter rail - no bare single-value `cardVisual` occupying the largest/dominant hero region unless the design marks it as a composite KPI treatment with context and rationale - no unresolved placeholders, ellipses, or prose-only wireframes If the block is missing these items, stop and revise the design contract before asking for approval or invoking `powerbi-report-authoring`. ## Locked Report Spec Output After Rounds 0-4, produce one file and save it under `./_brief/` in the current working directory: - `./_brief/report-spec.md` — the single source of truth for approval and implementation handoff. `report-spec.md` has two layers: 1. **Markdown sections** for user approval and readable context. 2. A fenced `yaml` block containing the exact `Design Brief:` returned by `powerbi-report-design` — the canonical implementation contract that `powerbi-report-authoring` consumes. If Markdown prose and the embedded YAML disagree, fix `report-spec.md` before building. Do not ask the authoring agent to choose between conflicting instructions. If the agent runtime exposes a dedicated session/scratch folder (for example a `session-state` path injected by the harness), you may also write a copy there for user visibility, but the canonical implementation handoff file remains `./_brief/report-spec.md` unless every later authoring step carries the alternate absolute path explicitly. ### `report-spec.md` template The user-approval doc and agent handoff contract. The Markdown captures sign-off granularity; the embedded YAML captures exact implementation intent. ````markdown # Report Spec ## Report identity - Report name: - Semantic model: - Audience: - Primary purpose: - Delivery target: ## User decisions and constraints - Scope: - Page count: - Interactivity: - Design direction: - Publishing: - Tooling: - Model edit permissions: - Accessibility: - Data caveats: ## Narrative - Core story: - Audience promise: - Key questions answered: ## Design identity (from `powerbi-report-design` Step 1) - Tone: - Signature: - Brownfield delta (if applicable): ## Page plan (archetypes from `powerbi-report-design` Step 3) 1. Page name - Archetype: - Layout variant (A/B/C): - Purpose: - Visuals: - Fields/measures: - Slicers/interactions: ## Design system summary - Theme name + base palette (1–2 lines): - Color semantics (which measure → which color, 1–2 lines): - Typography pairing (display + body): - Layout pattern (grid + gutter + density): - Accessibility commitments: ## Model requirements - Existing measures: - New measures: - New calculated columns: - Relationship/sort requirements: ## Canonical design contract Paste the exact fenced `yaml` block produced by `powerbi-report-design` here. Do not rewrite it from planner memory and do not replace its mechanical `layout_contract` with a freeform ASCII wireframe. The YAML block is authoritative for implementation. `powerbi-report-authoring` must implement this block; surrounding prose is context and conflict detection. ## Implementation notes - Model changes: - PBIR/report authoring: - Validation: - Desktop screenshot verification: - Publishing boundary: - Risks: ```` ### Required acceptance checks before approval Before writing the approval question, verify the spec meets all of the following. If any check fails, fix `report-spec.md` and the embedded `Design Brief:` block before asking for approval. - The block begins with `Design Brief:`. - It includes `generated_by: powerbi-report-design` and `contract_version`. - Every Markdown page has a matching `pages[]` entry. - Every page has `layout_contract.canvas`, `layout_contract.grid.regions`, and `layout_contract.placements`. - Every page has `layout_contract.space_audit` with empty `unplaced_regions` and an explicit empty-space/balance rationale. - Every page has a `page_title` textbox placement with non-empty title text. - Slicers are in a top-right `filters` region or a justified filter rail; no data visual starts under a slicer/header-band region. - No bare single-value `cardVisual` is the largest/dominant hero region unless the YAML explicitly describes a composite KPI treatment with context. - The approved YAML has no ellipses (`...`), unresolved placeholders, or pages/visuals promised in Markdown but omitted from the YAML. ## Approval Gate After writing `report-spec.md`, ask exactly one approval question: > Approve this report spec so I can start building? Recommended choices: 1. Approve — start building 2. Revise audience/purpose 3. Revise scope/page plan 4. Revise design/delivery Do not invoke authoring or publishing skills until the user approves. ## Implementation After Approval When the user approves, execute this sequence: 1. Re-read the approved canonical report spec (normally `_brief/report-spec.md`, or the explicitly carried alternate absolute path) and extract the embedded `Design Brief:` YAML block. Verify it has `generated_by: powerbi-report-design`, `contract_version`, one populated `layout_contract` per page, and `space_audit` per page before authoring. For greenfield, verify the canvas is FHD (`1920 x 1080`) unless the user chose another size, and verify the largest/dominant region is not a bare single-value `cardVisual`. 2. Mark the first implementation todo as in progress. 3. Connect to the semantic model. 4. Create/update required measures and calculated columns using whichever model-authoring path is available — a semantic-model authoring skill, a modeling MCP server, or direct TMDL edits — in that order of preference. 5. Validate each model change with DAX where possible. 6. After calculated-column or measure changes, trigger the lightweight recalculation supported by the chosen tool (e.g., XMLA refresh with `refreshType=Calculate`) unless a full source refresh is explicitly required and safe. 7. Export model changes to TMDL. 8. If the export writes a flat TMDL layout, reorganize into `definition/database.tmdl`, `definition/model.tmdl`, `definition/relationships.tmdl`, and `definition/tables/*.tmdl`. 9. Scaffold or copy the PBIP/PBIR report structure. 10. Author PBIR through `powerbi-report-authoring` guidance. 11. Generate report files. 12. Validate required files and JSON. 13. Open/reload in Power BI Desktop. 14. Screenshot pages. 15. Fix visual, slicer, data-binding, accessibility, and layout issues. 16. Publish only if the approved delivery target includes publishing. ## Fabric Publish Rules Publish only when the approved delivery target includes publishing. Hand the publish step to `powerbi-report-management`; do not author Fabric REST calls or `definition.pbir` `byConnection` payloads from this skill. See `powerbi-report-management` for the authoritative `byConnection` schemas (minimal API form and full XMLA form for local Desktop validation), LRO polling, and theme upload rules. Planner-level rules to respect when invoking `powerbi-report-management`: - Resolve workspace, report, and semantic model dynamically; do not hardcode IDs. - Include all PBIR definition parts on create/update; never send a partial definition. - Match custom theme upload paths exactly to the paths referenced in `report.json`. - Use `--verbose` for long-running operations and poll LROs to a terminal state (`Succeeded` / `Failed`). - Clean up any temporary publish scripts or payload files after the operation completes. ## Validation Standards A report is not complete until: - Required PBIP/PBIR files exist. - All JSON parses. - `definition.pbir` points to the expected semantic model. - Pages and visuals are generated in expected counts. - Power BI Desktop opens the `.pbip`. - Desktop reload succeeds. - Screenshot capture succeeds for at least the cover and any newly authored pages. - If published, Fabric LRO returns `Succeeded`. ## Anti-Patterns and Pitfalls - Generated PBIR is safer than hand-editing individual visual JSON files. - Model changes must be persisted before Desktop reload. - DAX filter direction can break dimension aggregations from fact-side flags. - High-cardinality slicers need search or prefix filtering. - Desktop validation catches issues that JSON validation cannot. - Fabric publishing is sensitive to `byConnection` schema and theme paths.