powerbi-report-planning

Power BI レポート計画スキル

このスキルは、新しい Power BI レポートの全ライフサイクルを統括します。

定義 -> 調査 -> 仕様策定 -> 承認 -> 構築 -> 検証 -> 公開

要件収集だけで完結するフローよりも意図的に範囲を広げており、レポート仕様をまとめるだけでなく、ユーザーの承認後に実装まで進めます。

必須／推奨／回避

必須

• 要件の確認、依存関係のチェック、承認、構築の順序付けが必要な、広範なレポート作成ワークフローではこのスキルを使用します。
• 要点を絞った確認の質問を一度に 1 つずつ行い、必要な決定が明確になった時点で終了します。
• _brief/report-spec.md を確定し、実装前に承認を得ます。
• 設計上の決定は powerbi-report-design に、ファイル操作は powerbi-report-authoring に委ねます。

推奨

• 質問を繰り返すのではなく、プロンプト、モデル、既存の PBIP ファイル、または以前のやり取りから明らかな回答を推測します。
• ページの範囲やビジュアルの提案を最終決定する前に、セマンティックモデルを調査します。
• 公開は任意とし、承認された場合にのみ進めます。

回避

• 既存の PBIR ファイルに対する小規模で限定的な編集には、このスキルを使用しないでください。
• ユーザーが確定済みのレポート仕様を承認する前に、構築を開始しないでください。
• 詳細なビジュアル設計や PBIR 作成に関するガイダンスを、関連スキルと重複させないでください。

使用する場面の例

ユーザーが新しい Power BI レポートの作成を希望し、次の両方が必要な場合にこのスキルを使用します。

1. ガイド付きの要件確認ワークフロー。
2. 承認後に実装へ進むための手順。

例：

• 「このセマンティックモデルを使って、新しい Power BI レポートを作成しましょう。」
• 「Power BI レポートの定義から構築まで手伝ってください。」
• 「レポート作成手順書を使って、新しいレポートを始めてください。」
• 「新しい Power BI レポート用の再利用可能なワークフローを作成してください。」

既存のレポートページに対する小規模な編集には、このスキルを使用しないでください。PBIR を直接作成する作業には powerbi-report-authoring を使用します。完全なガイド付きワークフローを伴わないビジュアルのレビューや新規設計のガイダンス（一度限りの「これを再設計して」や「どのような見た目にすべき？」など）には、powerbi-report-design を直接使用します。このスキルではラウンド 3～4 で設計スキルを使用しますが、置き換えるものではありません。

必須の運用ルール

1. 質問は一度に 1 つだけ行います。 確認事項ごとに ask_user を使用します。
2. 確認のラウンドは最大 3～5 回までとします。 各ラウンドでは、主要な質問を 1 つだけ行い、どうしても必要な場合に限り、追加の質問を 1 つ行えます。
3. 仕様を確定する前に、セマンティックモデルを調査します。 利用可能な場合はセマンティックモデルのスキルまたは MCP サーバーを使用します。それ以外の場合は、ローカルの TMDL/PBIP ファイルを直接調査します。
4. 依存関係を明示的に確認します。 Desktop、MCP、作成機能、Fabric への公開が利用可能だと決めつけないでください。
5. 構築前に、確定済みの _brief/report-spec.md を 1 つ作成します。
6. 実装前に承認を求めます。 ユーザーが明示的に承認するまで構築しないでください。
7. 承認後は、最初から最後まで構築します。 モデルの変更、PBIR の生成、検証、Desktop でのプレビュー、スクリーンショットを使った反復、任意の Fabric への公開を行います。
8. 公開が承認されない限り、ローカルでの編集はローカルにとどめます。
9. 把握済みの回答を再度尋ねないでください。 元のプロンプト、調査したファイル、または以前のラウンドで対象者、ページ数、納品先、範囲、設計の方向性がすでに示されている場合は、作業メモに記録して次に進みます。質問するのは、実際に曖昧な点やリスクのあるトレードオフだけです。

依存関係チェックリスト

実装前に、次の状況を記録してください。

依存関係	用途	必要となる場合
Power BI Desktop	PBIP を開く／再読み込みし、レポートを視覚的に検証する	ローカルでプレビューする場合は常に必要
PBIP/PBIR プロジェクト	ファイルベースのレポート作成	生成するレポートには常に必要
TMDL セマンティックモデル	モデルの永続化とソース管理	モデルを編集する場合に必要
powerbi-modeling-mcp	テーブル、列、メジャーの確認、メジャー／列の作成、セマンティックモデルのデプロイ	ライブでモデルを作成する場合に必要
powerbi-report-authoring skill	PBIR の検証、Desktop の再読み込み、ページのスクリーンショット撮影	レポート作成の検証に必要
powerbi-report-management skill	Fabric レポートの作成／更新／ダウンロード	Fabric への公開時のみ必要
Node.js	ジェネレーターを使用した PBIR 作成	再現可能なレポートを作成する場合に推奨

依存関係を利用できない場合は、計画を続け、該当するフェーズをブロック中／手動として記録してください。利用可能であるかのように装わないでください。

ラウンド構成

ラウンド 0 — セットアップと依存関係の確認

目標：セマンティックモデル、レポートの対象、利用可能なツールを特定します。

自動で確認できないことだけを質問します。

このレポートでは、どのセマンティックモデルまたはデータセットを使用しますか？

候補を特定できる場合は、具体的な選択肢を提示することを推奨します。対象範囲内の既存の Fabric セマンティックモデルとローカルの .SemanticModel フォルダーをすべて列挙し、選択肢として提示して、最適なものに「推奨」と付記します。例：

• <DiscoveredSemanticModelName>（推奨）
• その他の既存の Fabric セマンティックモデル
• 新しいローカルデータセット

次に、以下を確認します。

• 既存の .pbip、.Report、.SemanticModel フォルダー。
• TMDL ファイルが存在するかどうか。
• Power BI Desktop の自動化スクリプトが存在するかどうか。
• MCP 接続が利用可能か、または確立できるかどうか。
• Fabric への公開が求められているかどうか。

作業メモを出力します。

Dependency status:
- Semantic model:
- PBIP/PBIR:
- Desktop preview:
- Modeling MCP:
- Report-authoring skill:
- Fabric publishing:
- Node generator:

ラウンド 1 — 対象ユーザーと業務上の目的

目標：レポートの対象ユーザーと、そのレポートが支援する意思決定／業務を把握します。

プロンプトから対象ユーザーと達成すべき業務がどちらも明確な場合は、質問せず、推測した回答を要約します。それ以外の場合は、不明な点だけを一度に 1 つずつ質問します。

対象ユーザーが不明な場合に質問します。

このレポートの主な対象者は誰ですか？

推奨する選択肢：

1. 経営幹部／リーダー層 — 簡潔な KPI、傾向、リスク、意思決定
2. アナリスト — 探索、ドリルダウン、比較、表
3. オペレーター — モニタリング、例外、ステータス、アクションキュー
4. 外部の対象者 — 洗練されたストーリー、ガイド付きの説明、最小限のスライサー
5. 愛好家／ファン — 雑誌風の説明、豊富なビジュアル、ランキング

業務上の目的がまだ不明な場合に限り、次に質問します。

このレポートを使って、何をできるようにしたいですか？

推奨する選択肢：

1. 全体的なストーリーを把握する
2. パフォーマンスを追跡する
3. 外れ値や機会を見つける
4. エンティティまたはセグメントを比較する
5. 個々のレコード／プロフィールを調べる
6. 定期的なビジネスレビューに備える

以下を記録します。

Audience:
Primary purpose:
Tone:
Success criteria:

第2ラウンド — モデルのインベントリとスコープ

目標：モデルを調査し、ユーザーがすでに指定したスコープを再確認せずに、初回ビルドのスコープ境界を定義します。

利用可能なモデル検査機能を使用します。該当するもののうち、優先順位が最も高いものを選んでください。

1. インストールされている場合は、セマンティックモデル作成スキル。
2. モデリング MCP サーバー（例：powerbi-modeling-mcp-*）— ライブモデルに接続し、テーブル／列／メジャー／リレーションシップを一覧表示して、ライブ検証用に DAX を実行します。
3. ライブ接続が利用できない場合は、ローカルの TMDL ファイル（definition/model.tmdl、definition/tables/*.tmdl、definition/relationships.tmdl）を直接読み取ります。

ユーザー向けプロンプトにツール名をハードコードしないでください。検査の意図を説明し、利用可能なツールをエージェントに選ばせます。

次の内容を要約します。

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

検査後、元のリクエストと以前の回答から初回ビルドのスコープを推測します。ユーザーがすでにページ数、レポートの種類、またはコンテンツの範囲（例：「4ページのダッシュボードを作成」）を指定している場合は、スコープについて単独で質問しないでください。代わりに、作業メモに境界を要約します。

First-build scope:
- <focused first build / standard report / operational app / narrative report>
- inferred from: <user prompt | prior answer | model shape>
- included now:
- deferred:

境界が不明確、広すぎる、またはリスクを伴う場合に限り、スコープについて質問します。質問する場合は、一般的な初回ビルドの選択肢ではなく、調査したモデルに基づいた選択肢を提示します。例：

このモデルでは、売上、製品、地域、割引、収益性を扱えます。 今回の初回ビルドでは、経営層向けのパフォーマンスに焦点を絞りますか。それとも、製品／顧客の詳細な分析も含めますか？

第3ラウンド — ストーリーとページ計画

目標：モデルとスコープをページ構成に落とし込みます。

ページレベルのアーキタイプの選定と構成に関するガイダンスについて、powerbi-report-design を呼び出すか、明示的に参照します。ビジュアルの選定はデザインスキルが担います。このドキュメントで選定表を重複して記載しないでください。第2ラウンドのデータ形状に基づいて、ユーザーの承認を得るためのレポート構成案を2～3個提示します。

デザインスキルに含まれる5つのアーキタイプは、経営層向けサマリー、運用モニター、分析キャンバス、ナラティブストーリー、比較ベンチマークです。レイアウトのバリエーション、複数アーキタイプを使うレポート、ページ間でのバリエーションの使い分けについては、デザインスキルのアーキタイプと構成のガイダンスを使用します。

第2ラウンドで推測した初回ビルドのスコープを適用した後に限り、次のように質問します。

どのレポート構成を使用しますか？

名前付きの構成案を2～3個提示します（例：複数ドメインにまたがる依頼では、経営層向けランディングページ＋分析ページ＋ランキング比較ページ、焦点を絞った依頼では、単一の経営層向けランディングページ）。第1～2ラウンドの内容に基づいて1つを推奨し、(Recommended) と記載します。

ユーザーが選択した後、回答内にページ一覧を作成します。

Proposed pages:
1. <Page> — archetype — purpose — core visuals — fields/measures
2. <Page> — archetype — purpose — core visuals — fields/measures
<repeat for each approved page>

スライサーとインタラクションを記録します。

• グローバルスライサー
• ページ固有のスライサー
• カーディナリティの高いディメンション向けの検索／プレフィックススライサー
• ドリルスルー／プロファイルページ
• 必要に応じたブックマーク／ナビゲーション

ラウンド 4 — デザインアイデンティティ、アクセシビリティ、デリバリー

目標：デザインアイデンティティ、アクセシビリティの基準、デリバリー先を確定します。

デザインアイデンティティとテーマの方向性について、powerbi-report-design を呼び出すか、明示的に参照してください。デザインアイデンティティ（トーン＋シグネチャー）はデザインスキルが担います。ここで独自の別の語彙を作らないでください。デザインスキルのアイデンティティに関するガイダンスを使ってトーン＋シグネチャーの組み合わせを選び、ユーザーに提示してください。

質問：

このレポートからどのような印象を受けるべきですか？

ラウンド 1～2 で確認した対象者とドメインに合わせた、具体的なアイデンティティの選択肢を 2～3 個提示してください。それぞれの選択肢では、レポートの印象と、それが意味する代表的なビジュアル表現を 1 つ挙げてください。1 つを推奨し、(Recommended) と記してください。

ユーザーにブランドガイドラインがある場合は、一般的なトーンではなく、ブランドを前面に出した選択肢を 1 つ含めてください。

デリバリー先が不明な場合に限り、続けて質問してください。

完成したレポートはどこに配置しますか？

推奨する選択肢：

1. まずローカルの PBIP のみ
2. 既存の Fabric ワークスペースに公開
3. Fabric で新しいセマンティックモデル＋レポートを作成
4. 既存の Fabric レポートを更新
5. まずローカルで作成し、公開については後で決める

デザインのデフォルト設定（これらはデザインスキルの注意事項と基本テーマに基づき、ユーザーが変更しない限り自動的に適用されます）：

• すべてのテキストと背景の組み合わせで、アクセシビリティに配慮したコントラスト（最低 WCAG AA）を使用します。
• 赤地に赤の配色や、コントラストの低い配色は避けます。
• 非推奨の map／filledMap ビジュアルより、Azure Map を優先します。
• すべてのグラフに代替テキストを追加します。
• カーディナリティの高いフィールドには、検索可能なドロップダウンスライサーを使用します。
• 選択肢が少ないカテゴリーフィールドにのみ、タイル／リストスライサーを使用します。
• 詳細テーブルはページの下部近くに配置します。
• レポートの操作性は予測しやすく、一貫性のあるものにします。

デザイン契約ゲート

承認用の _brief/report-spec.md を作成する前に、powerbi-report-design から正式な Design Brief: YAML ブロックを取得してください。プランナーは要件、モデルの一覧、ページの目標、ユーザーの制約をデザインスキルに提供してもかまいませんが、競合する詳細なデザインの骨組みを作成してはいけません。

正式なデザインブロックには、次の項目を含める必要があります。

• generated_by: powerbi-report-design
• contract_version
• ページプランの各ページに対応する pages[] エントリ
• pages[].layout_contract.canvas
• pages[].layout_contract.grid.regions
• pages[].layout_contract.placements
• pages[].layout_contract.space_audit
• 各ページに、空でないタイトルテキストを含む page_title テキストボックスの配置
• 右上の filters 領域、または妥当な理由が示されたフィルターレールへのスライサーの配置
• 最大／最も目立つヒーロー領域を、単一値だけの cardVisual が占めていないこと。ただし、デザインで文脈と根拠を伴う複合 KPI 表現として指定されている場合を除きます。
• 未解決のプレースホルダー、省略記号、文章だけのワイヤーフレームがないこと

ブロックにこれらの項目が含まれていない場合は、承認を求めたり powerbi-report-authoring を呼び出したりする前に作業を止め、デザイン契約を修正してください。

ロック済みレポート仕様の出力

ラウンド 0～4 の後、1 つのファイルを作成し、現在の作業ディレクトリにある ./_brief/ に保存してください。

• ./_brief/report-spec.md — 承認と実装の引き継ぎに使用する唯一の信頼できる情報源です。

report-spec.md は次の 2 層で構成されます。

1. ユーザーの承認と読みやすいコンテキストのための Markdown セクション。
2. powerbi-report-design が返した正確な Design Brief: を含む、フェンス付きの yaml ブロック。これは powerbi-report-authoring が使用する正式な実装契約です。

Markdown の文章と埋め込み YAML の内容が食い違う場合は、作成に進む前に report-spec.md を修正してください。矛盾する指示のどちらに従うかを、オーサリングエージェントに選ばせてはいけません。

エージェントのランタイムに専用のセッション／スクラッチフォルダー（ハーネスから挿入された session-state パスなど）がある場合、ユーザーに見えるよう、そこにもコピーを保存してかまいません。ただし、後続のすべてのオーサリング手順で代替パスの絶対パスを明示しない限り、正式な実装引き継ぎファイルは ./_brief/report-spec.md のままです。

report-spec.md テンプレート

ユーザー承認用ドキュメントであり、エージェントへの引き継ぎ契約です。Markdown には承認の粒度を記録し、埋め込まれた YAML には実装の意図を正確に記録します。

# 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: <named entry from tone-catalog, e.g. "Editorial Newsroom">
- Signature: <one defining move, e.g. "tabular numerals + display serif headlines">
- Brownfield delta (if applicable): <current_tone → target_tone>

## Page plan (archetypes from `powerbi-report-design` Step 3)
1. Page name
   - Archetype:                      <Executive Summary | Analytical Canvas | …>
   - Layout variant (A/B/C):         <plus one-sentence variant_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:

承認前に必須の受け入れチェック

承認を求める前に、仕様が以下のすべてを満たしていることを確認します。いずれかのチェックに失敗した場合は、承認を求める前に report-spec.md と埋め込みの Design Brief: ブロックを修正してください。

• ブロックが Design Brief: で始まっていること。
• generated_by: powerbi-report-design と contract_version が含まれていること。
• Markdown の各ページに、対応する pages[] エントリがあること。
• 各ページに layout_contract.canvas、layout_contract.grid.regions、layout_contract.placements があること。
• 各ページに layout_contract.space_audit があり、unplaced_regions が空で、空白やバランスについて明示的な根拠が示されていること。
• 各ページに、タイトルテキストが空でない page_title テキストボックスの配置があること。
• スライサーが右上の filters 領域、または正当な理由のあるフィルターレールに配置されていること。スライサー／ヘッダーバンド領域の下からデータビジュアルが始まっていないこと。
• YAML でコンテキストを含む複合 KPI 表現が明示的に記述されている場合を除き、単独の値を表示するだけの cardVisual が最大または最も目立つヒーロー領域になっていないこと。
• 承認済みの YAML に省略記号（...）、未解決のプレースホルダー、Markdown で示されているものの YAML から漏れているページ／ビジュアルがないこと。

承認ゲート

report-spec.md を作成した後、承認を求める質問を1つだけ、次のとおり尋ねます。

このレポート仕様を承認して、作成を開始してもよいですか？

推奨される選択肢：

1. 承認 — 作成を開始
2. 対象者／目的を修正
3. 範囲／ページ計画を修正
4. デザイン／納品方法を修正

ユーザーが承認するまで、作成または公開に関するスキルを呼び出さないでください。

承認後の実装

ユーザーが承認したら、次の手順を実行します。

1. 承認済みの正式なレポート仕様（通常は _brief/report-spec.md、または明示的に引き継がれた別の絶対パス）を再読し、埋め込まれた Design Brief: YAML ブロックを抽出します。作成を始める前に、generated_by: powerbi-report-design、contract_version、各ページに1つずつ設定済みの layout_contract、および各ページの space_audit があることを確認します。新規作成の場合は、ユーザーが別のサイズを選んでいない限り、キャンバスが FHD（1920 x 1080）であること、また最大または最も目立つ領域が単独の値を表示するだけの cardVisual ではないことを確認します。
2. 最初の実装タスクを進行中としてマークします。
3. セマンティックモデルに接続します。
4. 利用可能な方法のうち、次の優先順位で必要なメジャーと計算列を作成／更新します。セマンティックモデル作成スキル、モデリング用 MCP サーバー、または TMDL の直接編集。
5. 可能な場合は、各モデル変更を DAX で検証します。
6. 計算列またはメジャーの変更後、選択したツールでサポートされている軽量な再計算（例：refreshType=Calculate を指定した XMLA 更新）を実行します。ただし、完全なソース更新が明示的に必要で、安全に実施できる場合を除きます。
7. モデルの変更を TMDL にエクスポートします。
8. エクスポートによってフラットな TMDL レイアウトが生成された場合は、definition/database.tmdl、definition/model.tmdl、definition/relationships.tmdl、definition/tables/*.tmdl に整理します。
9. PBIP/PBIR レポート構造をひな形から作成するか、コピーします。
10. powerbi-report-authoring のガイダンスに従って PBIR を作成します。
11. レポートファイルを生成します。
12. 必須ファイルと JSON を検証します。
13. Power BI Desktop で開く／再読み込みします。
14. 各ページのスクリーンショットを撮ります。
15. ビジュアル、スライサー、データバインド、アクセシビリティ、レイアウトの問題を修正します。
16. 承認済みの納品先に公開が含まれている場合に限り、公開します。

Fabric の発行ルール

承認済みの納品先に発行が含まれる場合にのみ発行してください。発行手順は powerbi-report-management に委ねてください。このスキルで Fabric REST 呼び出しや definition.pbir の byConnection ペイロードを作成しないでください。 権威ある byConnection スキーマ（最小 API 形式と、ローカルの Desktop 検証用の完全な XMLA 形式）、LRO のポーリング、およびテーマのアップロードルールについては、 powerbi-report-management を参照してください。

powerbi-report-management を呼び出す際に遵守する、プランナーレベルのルール：

• ワークスペース、レポート、セマンティックモデルは動的に解決し、ID をハードコードしないでください。
• 作成／更新時には、PBIR 定義のすべてのパーツを含めてください。部分的な定義は決して送信しないでください。
• カスタムテーマのアップロードパスを、report.json で参照されているパスと正確に一致させてください。
• 実行時間の長い操作では --verbose を使用し、LRO が終端状態（Succeeded／Failed）になるまでポーリングしてください。
• 操作の完了後、一時的な発行スクリプトやペイロードファイルをすべて削除してください。

検証基準

以下を満たすまで、レポートは完成していません。

• 必要な PBIP／PBIR ファイルが存在する。
• すべての JSON が解析できる。
• definition.pbir が想定されるセマンティックモデルを指している。
• ページとビジュアルが想定された数だけ生成されている。
• Power BI Desktop で .pbip が開く。
• Desktop の再読み込みが成功する。
• 表紙および新たに作成したページについて、スクリーンショットのキャプチャが成功する。
• 発行した場合、Fabric LRO が Succeeded を返す。

アンチパターンと落とし穴

• 生成された PBIR のほうが、個々のビジュアル JSON ファイルを手動で編集するより安全です。
• Desktop の再読み込み前に、モデルの変更を保存する必要があります。
• DAX のフィルター方向によって、ファクト側のフラグを使ったディメンションの集計が機能しなくなる場合があります。
• カーディナリティの高いスライサーには、検索またはプレフィックスフィルターが必要です。
• Desktop での検証では、JSON の検証で検出できない問題が見つかります。
• Fabric への発行は、byConnection スキーマとテーマのパスの影響を受けやすいです。