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".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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".
metadata
{"version":"0.1.0"}
Power BI Report Planning Skill
This skill orchestrates the full lifecycle for a new Power BI report:
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:
A guided requirements workflow.
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
Ask one question at a time. Use ask_user for each clarification.
Run 3-5 clarification rounds maximum. Each round may have one primary
question and, only if absolutely necessary, one follow-up.
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.
Check dependencies explicitly. Do not assume Desktop, MCP, authoring, or
Fabric publishing are available.
Produce one locked _brief/report-spec.md before building.
Ask for approval before implementation. Do not build until the user
explicitly approves.
When approved, build end-to-end. Model changes, PBIR generation,
validation, Desktop preview, screenshot loop, and optional Fabric publish.
Local edits stay local unless publishing is approved.
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:
<DiscoveredSemanticModelName> (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.
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.
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:
A semantic-model authoring skill, if installed.
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.
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:
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:
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:
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:
Local PBIP only first
Publish to an existing Fabric workspace
Create new semantic model + report in Fabric
Update an existing Fabric report
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:
Markdown sections for user approval and readable context.
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.
# 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: <namedentryfromtone-catalog, e.g. "EditorialNewsroom">- Signature: <onedefiningmove, e.g. "tabularnumerals + displayserifheadlines">- Brownfield delta (if applicable): <current_tone → target_tone>## Page plan (archetypes from `powerbi-report-design` Step 3)1. Page name
- Archetype: <ExecutiveSummary | AnalyticalCanvas | …> - Layout variant (A/B/C): <plusone-sentencevariant_rationale> - 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:
Approve — start building
Revise audience/purpose
Revise scope/page plan
Revise design/delivery
Do not invoke authoring or publishing skills until the user approves.
Implementation After Approval
When the user approves, execute this sequence:
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.
Mark the first implementation todo as in progress.
Connect to the semantic model.
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.
Validate each model change with DAX where possible.
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.
Export model changes to TMDL.
If the export writes a flat TMDL layout, reorganize into
definition/database.tmdl, definition/model.tmdl,
definition/relationships.tmdl, and definition/tables/*.tmdl.
Scaffold or copy the PBIP/PBIR report structure.
Author PBIR through powerbi-report-authoring guidance.
Generate report files.
Validate required files and JSON.
Open/reload in Power BI Desktop.
Screenshot pages.
Fix visual, slicer, data-binding, accessibility, and layout issues.
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.pbirbyConnection 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.
