build-report

関連スキル

レポートが市場規模の推定、指標の診断、KPI レポート、製品・ビジネス分析、データ品質チェック、または検証に依存する場合は、レポートを作成する前に、目的に合った分析スキルを使用してください。

レポートの作成

ダッシュボード、ノートブックのみの出力、一時的なチャット要約ではなく、長く利用できる分析レポートが必要な場合に、このスキルを使用してください。レポートでは、読者向けの説明、対象読者、根拠の配置、図表の配置、留意事項、ソースのメタデータ、引き継ぎを扱います。基となる分析には、引き続き適切な分析、ノートブック、データ品質、診断、KPI、または製品分析のワークフローを使用してください。

このスキルが直接選択された場合、またはレポートモードのワークフローに含まれている場合、選択したレポート形式が完成するか、具体的な阻害要因が記録されるまでは、作業は完了していません。チャットのみの文章、インラインウィジェット、ローカル URL、またはレポートの形式を省略した場当たり的な成果物で完了してはいけません。インライン要約やノートブックの出力は進捗を示す根拠として扱い、レポートの代わりにしてはいけません。このスキルを選択した後は、グラフ、表、プレビューを、選択したレポート形式にのみ配置してください。ユーザーがインライン形式、チャットのみ、短い回答／成果物なしを明示的に求めた場合、レポート／ファイル／成果物を作成しないよう依頼した場合、または別の主要な成果物を選択した場合は、レポート作成を明示的に免除できます。「レポート」という言葉がないことや、診断、推奨、規模推定、状況報告を直接尋ねていることから、免除を推測してはいけません。

スキルの設定

実行ごとに、レポートの提供モードを必ず1つだけ選択してください。

• Codex デスクトップ：デフォルトで mcp-app を使用します。
• ChatGPT Web の Work Mode であることが確実に確認されている場合：その環境では MCP アプリのレポート描画が機能しないため、html を使用します。MCP サーバーやその他の呼び出し可能なツールは、引き続き根拠の情報源として有効です。
• Work Mode のシグナルがあるものの、環境が不明、またはデスクトップではない場合：html を使用します。環境が不明であることを、MCP アプリのレポートを描画してよい根拠として扱ってはいけません。Codex デスクトップの MCP デフォルトを適用できるのは、surface = codex_desktop という明確なシグナルがある場合だけです。
• MCP アプリのレポート描画が利用できないその他のランタイム：html を使用します。
• 不明または未分類のランタイム：レポートを省略せず、移植性の高い html をデフォルトで使用します。

Codex デスクトップでは、ユーザーが HTML、オフラインでの移植性、ファイル形式の成果物、または MCP による描画を使わないことを明示的に求めた場合、後続形式への変換に HTML が必要な場合、または MCP アプリのレポートを実際に試みたものの、機能を利用できない、もしくは文書化された描画の制限を超えたため失敗した場合に限り、html を使用してください。

選択した MCP アプリのレポートが、対象を絞った修正を1回行っても描画できない場合は、ユーザーが HTML を明示的に拒否していない限り、同じ実行内で html に切り替えてください。描画の失敗によって提供モードは変更されますが、レポートが不要になるわけではありません。どちらの形式も作成できない場合は、具体的な阻害要因と試した形式を記録してから完了してください。

実行ごとに、提供モードを必ず1つだけ選択してください。ユーザーが別の提供モードを個別の追加依頼として明示的に求めた場合を除き、MCP アプリのレポートと静的な report.html を並行して作成してはいけません。Codex デスクトップで HTML を明示的に選択した場合、ChatGPT Web の Work Mode を使用する場合、PDF、Google Docs、Google Slides への変換用に HTML を作成する場合を含め、HTML を選択したすべてのレポートでは、recharts-html.md に記載された、Recharts を HTML に事前コンパイルする方法を使用してください。また、納品する HTML には、同じデータを使った読みやすい静的なフォールバックも含めてください。

ワークフロー

1. レポートの目的を定義します。

   レポートで支援するユーザーの質問、意思決定または行動、主な対象読者、対象範囲、期間、比較基準、成功基準、意思決定に役立つレポートに必要な要素を明示します。対象読者は必ず1つ選んでください。

   • product stakeholders: プロダクト、ビジネス、リーダーシップ、戦略、診断、KPI レポート、および一般的なステークホルダー向けレポートのデフォルトです。
   • technical: ユーザーが技術レポートまたは手法優先のレポートを求めた場合、あるいはレポートの主な価値が指標定義、測定設計、統計、モデリング、実験、検証といった方法論にある場合に限ります。

   作業が異常に方法論重視であるにもかかわらず、ユーザーが技術的な読者を求めていない場合は、切り替える前に確認してください。

2. 一致する読者向け仕様を読みます。

   エビデンスを収集したり、レポートの骨子を形作ったり、レポートの表面を起草したりする前に、一致する読者向け仕様をちょうど 1 つ読みます。

   • product stakeholders には executive-report.md
   • technical には technical-report.md

   選択した読者向け仕様は、以下のワークフローの代替ではなく、レポート品質の契約として扱ってください。その Required Structure の項目をレポート計画または補足ソースノートに記録し、一致する仕様を読めない場合はブロッカーで停止します。

3. エビデンスを収集し、範囲を定めます。

   レポートを支えるために必要なソースデータ、指標定義、分母、前提、要求された切り口、注意事項、ノートブック、SQL、スクリプト、クエリのパーマリンク、ソース文書、レビュー済みデータセットを棚卸しします。主張を起草する前に曖昧さを解消します。要求された指標や切り口をサポートできない場合は、その理由を記録し、それを追加するためにどのようなエビデンスが必要かを述べます。プロセスノート、ソース目録、再現性ノートは、表示されるレポート本文ではなく、ソースメタデータ、ソースノート、または補助成果物に保持します。

   このスキルが直接選択され、ユーザーが別のサンプルを指定したり添付したりせずに、明示的に「サンプルデータを使用する」または「サンプルデータを使用して」レポートを作成するよう求めた場合、その表現は同梱の合成デモの選択として扱います。このスキルを基準に demo-product-growth.csv を解決し、それらの行を分析し、合成であるとラベル付けし、ワークスペースで代替を探したり、置き換えデータを作成したりしないでください。

4. レポートの骨子を蒸留します。

   配信面を選ぶ前に、次の項目を持つ、簡潔で答えを先頭に置くレポートの骨子を書くか、頭の中で検証します。

   • 問い
   • 意思決定に役立つ答え
   • 指標、コホート、分母、時間枠、比較基準
   • 要求されたセグメントまたはドライバーごとの知見と、それを支えるエビデンス
   • 答えが比較的である場合、因果に近い場合、または意外である場合の感度分析または検証チェック
   • 解釈を変えうる注意事項
   • 推奨される次のステップ、モニタリングポイント、または未解決の問い

   レポートのセグメントが明確に分離されていることを確認し、重複する機能や指標の網羅を削除します。各主要セグメントはレポート内で 1 つの明確な役割を持ち、主張をエビデンス、解釈、具体的な含意と組み合わせるべきです。

   骨子がタイトル、エグゼクティブサマリー、および 1 つのチャートまたは表のみの場合は、ユーザーが明示的に簡潔版を求めていない限り、レンダリングする前に停止してエビデンスの経路を拡張してください。

5. 読者向けの構造を計画します。

   表面を構築する前に、順序付けられた主要セグメント、表示されるセグメントタイトル、および各セグメントの意図されたエビデンス形式を起草します。実際のデータが利用可能な場合、定量的な知見にはデフォルトでビジュアルを使用し、正確な参照、監査の詳細、またはチャートでは要点が不明瞭になる場合には表を使用します。定量的なセグメントにビジュアルがない場合は、省略理由をソースノートまたは補助成果物に記録します。

   計画されたすべての主要セグメントには、最終レポートに表示される読者向けタイトルが必要です。セクションタイトルを担うために、チャートヘッダー、表タイトル、またはレンダリングされない構造だけに依存しないでください。

   構築する前に、レポートの深さゲートを適用します。

   • エグゼクティブサマリーは、エビデンスセクションには含まれません。
   • 定量的な調査結果を含むレポートでは、エビデンスを解釈するために定義が必要になる前に、指標やコホートの定義を明示する必要があります。
   • 比較レポートでは、集計値だけでなく、セグメントレベルの解釈を含める必要があります。
   • 因果関係に関連するレポート、または行動の違いを扱うレポートでは、該当する調査結果の近くに、検証、感度分析、または制限に関する注記を少なくとも1つ含める必要があります。
   • ナラティブが1ブロックのみで、証拠がチャートや表だけのレポートは薄すぎます。ただし、ユーザーが簡潔な概要、インラインでの回答、または単一チャートの読み解きを明示的に求めた場合は除きます。

6. レポートの基準と対象読者の要件を適用します。

   全体構成ができたら、このスキルに関連する基準を適用します。計画した各主要セグメントを、選択した対象読者仕様のRequired Structureの項目に対応付け、統合、名称変更、順序変更、または省略した項目があれば、その理由を記録します。

7. ビジュアルと表を設計します。

   レポート内のすべてのビジュアルは、チャートの選択、チャート仕様、および最終コンテキストのQAのために$visualize-dataを通してください。チャート選択の根拠、検証メモ、QAの詳細は、ユーザーが方法論を求めている場合、または詳細が読者向けの結論を変える場合を除き、作業メモ、ソースノート、または補足資料に記載してください。すべてのビジュアルと表が、装飾的な情報として存在するのではなく、具体的なレポートの主張を裏付けていることを確認してください。レンダリングの前に、各ビジュアルに隣接する説明段落を計画してください。チャート、表、プレビューの出力は、選択したレポート形式用に確保してください。

8. 提供形式を1つ選び、作成します。

   レポートの骨子とエビデンス計画が明確になった後に選んだ単一の提供形式を使用します。ユーザーが別個のフォローアップとして明示的に求めない限り、2つ目の形式を追加しないでください。

   選択した形式は、レポートの読み進め方、明示的なタイトル、エビデンスの順序、注意事項、ソースメタデータを維持するように作成します。選択した形式の実装ガイダンスとしてReport Standardsの提供形式仕様を使用し、レポート作成ワークフローの代わりとして使わないでください。

   ユーザーがMCPアプリのレポートまたはダッシュボードをホスト済みリンクとして共有するよう求めた場合は、MCPアプリが有効になった後、アーティファクトアプリのSite Creator共有手順を使用します。export_artifact_packageを呼び出して、現在のマニフェスト、範囲が限定されたスナップショット、パッケージメタデータ、インラインで安全に使えるソーステキスト、および実際のMCPアーティファクトランタイムをSite Creator互換のアプリとして生成します。単独のHTMLを独自に作成したり、MCP専用のホストペイロード状態に依存するビューアーを公開したりしないでください。sites-hostingのワークフローに従い、ユーザーがより限定的なアクセスを求めない限り、新たにホストするレポートのアクセス範囲はworkspace_allをデフォルトにしてください。

   既存のレポートを修正する場合は、現在レンダリングされているレポートとソースメタデータを開始時のアーティファクトとして扱います。ユーザーが明示的に変更を求めた場合、または依頼された編集によって狭い範囲の関連更新が避けられない場合を除き、既存のすべてのセクション、ビジュアル、表、ソース、データセット、タイトル、注意事項をそのまま維持してください。セクションの追加、チャートの差し替え、ビジュアルのスタイル変更、またはレポートの一部のカスタマイズを求める依頼は、レポートの残りを要約、置換、並べ替え、または削除する依頼ではありません。選択した形式で修正版レポート全体をレンダリングしてください。以前のレポートが完成版だった場合、セクションのみの、簡略化された、または一部だけの差し替えアーティファクトを引き渡さないでください。 検証またはレンダリングの問題が発生した後の修正パスでは、前回の完全なレポート成果物をその場でパッチしてください。変更は、影響を受けたビジュアル、表、セクション、データセット、またはソース、およびそれらに直接依存する参照に限定してください。選択したサーフェスがこれらの概念を公開している場合は、無関係な id、読み取り順序、ナラティブテキスト、注意事項、推奨事項、ソースメタデータ、パッケージメタデータ、データセットを変更せずに保持してください。レンダリングの前に、旧版と新版の成果物構造を比較し、意図した部分だけが変更されたことを確認してください。前回の完全な成果物が利用できない場合は、停止し、記憶から短縮版を作り直すのではなく、そのブロッカーを報告してください。

9. 完成したレポートを検証します。

   ソースファイルだけでなく、レンダリングされたレポートそのものをレビューしてください。以下を確認します：

   • レポートの冒頭がユーザーに直接答えている
   • すべての主要なセグメントに表示されるタイトルがある
   • 主張、ビジュアル、表、注意事項、含意が意図した読み取り順序で表示されている
   • 選択した配信サーフェスが、そのモード固有の基準を満たしている
   • 裏付けとなるエビデンスとソースノートが監査可能性に十分である

   これらのチェックのいずれかが失敗した場合は、引き渡しの前にレポートを修正してください。

10. 選択したレポートを引き渡します。

選択したレポート成果物の結果またはブロッカーを先頭に記載してください。次に、該当する MCP アプリ成果物または HTML レポートのパスのみを、裏付けとなるソース、SQL、コード、ノートブック、チャートの成果物とともに列挙してください。HTML モードでは、実際のインタラクティブな report.html ファイルが主要な成果物です。レンダリングされた PNG またはスクリーンショットは、ラベル付けされた非インタラクティブな QA プレビューとしてのみ含めることができます。image.png、スクリーンショット、またはその他の平坦化された画像を、レポート引き渡しの唯一の手段として使用しないでください。ホストが HTML をインラインでレンダリングできない場合は、平坦化するのではなく、.html ファイルを添付またはリンクしてください。引き渡しの前に、品質基準に対してレポートを自己監査してください。HTML の共有または変換が必要かつ安全な場合は、プレゼンテーションサーフェスを解決してください。そうでない場合は、共有が安全でなかった、利用できなかった、または明示的に放棄された理由を記録してください。レポートの代わりにチャットの要約で代替しないでください。

レポート基準

PDF エクスポート仕様

ユーザーが Data Analytics レポート、ダッシュボード、またはインラインチャートサーフェスを PDF にエクスポートするよう求めた場合は、report-to-pdf を使用してください。このサブスキルが PDF 変換の仕組みを担うため、このルートワークフローは配信モードに中立なまま保たれます。

MCP アプリレポート仕様

選択したレポートサーフェスが MCP アプリレポートである場合は、mcp-app-report.md を読んでください。このファイルが MCP アプリレポートの仕組みを担うため、このルートワークフローは配信モードに中立なまま保たれます。

HTML レポート仕様

• Skill Configuration の納品ルールに該当する場合に限り、HTML モードを使用してください。Codex デスクトップでは、ユーザーまたは後続の変換処理で HTML が明示的に必要とされていない限り、MCP を試す前に HTML モードを選択しないでください。
• HTML レポートを作成する場合は、すべて recharts-html.md を読み、../../assets/html-report-shell.html を基に作成してください。レポートの data-contract-section 属性は、選択した対象読者の仕様に合わせて保持または調整してください。ライブチャートには同梱の Recharts ランタイムを使用し、同じデータを使った静的な SVG／テーブルのフォールバックを HTML 内に直接保持してください。
• すべての HTML レポートで、シェルのシステム設定に応じた外観の自動切り替えを維持してください。<meta name="color-scheme" content="light dark">、セマンティックカラーのトークン、@media (prefers-color-scheme: dark) によるトークンの上書きを保持してください。レポートの内容、チャート、フォールバック、ソースツールチップ、フォーカス状態を、ライトモードとダークモードの両方で確認してください。この動作を手動切り替え専用のテーマ機能に置き換えないでください。
• HTML の読み進め方はレポートらしい構成にしてください。最初に回答を示し、セグメントのタイトルを明確にし、根拠と解釈を併記し、必要な箇所に注意点を記載してください。また、ユーザーから明示的に求められない限り、表示される「ソース」「注記」「再現性」の付録を末尾に追加せず、ソースのメタデータは保持してください。
• HTML レポート内の、ソースに基づく定量値にはすべて、その値に直接関連付けられたソースツールチップを付けてください。見出しや KPI の値、本文中の数値の主張、表の値、取得データに基づくその他の表示数値も含まれます。ツールチップには Source: <ソースシステム、コネクター、または成果物> を記載してください。構造化データの場合は Table: <完全修飾テーブル名またはビュー名> も記載してください。値が結合データや複数の入力から導出されている場合は、重要な寄与元のソースとテーブルをすべて記載してください。表形式ではない根拠の場合は、Table を正確な Dataset、File、または Document 名に置き換えてください。出所を推測してはいけません。テーブルやソースを特定できない場合は、その旨を明示し、ソース注記にも不明であることを残してください。
• HTML のソースツールチップは、シェルの source-tooltip パターンを使い、ホバーとキーボードフォーカスで実際に表示される仕組みにしてください。ネイティブの title 属性だけに頼らないでください。操作しなくても数値を読めるようにし、ツールチップの文面は簡潔にしてください。各ツールチップを、それが示す数値に関連付けてください。共有ツールチップは、同じグループ内のすべての数値を明確に示し、出所もすべて同じである場合に限り使用できます。
• 本文中の数値、KPI やメトリックカードの数値、表の値、チャートの数値には、共通の source-tooltip-content スタイルを使用してください。カード、本文、表、チャートごとのツールチップ用スタイルを作らないでください。前景色、背景色、タイポグラフィ、パディング、角丸、影を統一してください。また、周囲の数値から控えめな色や強調色を継承しないよう、ツールチップのテキストには共通の前景色を明示的に指定してください。
• ライブの Recharts チャートと、同じデータを使う静的なフォールバックでは、HTML だけで各マークの出所を示せません。各チャート図に、プロットされた値に使われた重要なソースと完全修飾テーブル名をすべて記載した、アクセシブルなソースツールチップを付けてください。ただし、ホバーとフォーカスのトリガーは、図全体やチャート画像ではなく、目に見える Source 表記だけに設定してください。閲覧者向けのツールチップに、クエリ文字列、認証情報、リクエスト ID、ローカルパスを含めないでください。
• ツールチップを見つけられるよう、チャート図に目に見えるソース表記を追加してください。印のない画像へのホバーに頼らないでください。ソースに基づく本文中の数値には、点線の下線など、出所が分かる表示を維持してください。
• 引き渡す前に、シェルやスクリーンショットだけでなく、生成された report.html 自体を確認してください。ライブ Recharts のマウントが正しく描画されること、スクリプトが実行されなくても同じデータのフォールバックが読み取れること、納品ファイルが兄弟ファイルのチャート画像、ローカルランタイム、リモートスクリプトに依存していないことを確認してください。ソースに基づく表示数値がすべて source-tooltip で囲まれていること、すべてのツールチップに実在する出所情報があり、プレースホルダーが含まれていないこと、すべてのチャート図に目に見えるソース表記があり、ホバー／フォーカスの対象がチャート画像全体ではなく Source 表記であることを確認してください。本文中、カード、表、チャートの各ツールチップを代表例で比較し、計算後の前景色、背景色、タイポグラフィ、パディング、角丸、影が統一されていることを確認してください。納品するレポートを画像化してはいけません。report-to-google-doc または report-to-google-slides は、ライブ MCP アプリのレポートではなく、HTML レポートにのみ使用してください。

Narrative

• すべてのレポートには、読者向けの短く平易な英語のタイトルが必要です。HTML レポートでは、ドキュメントタイトルと表示されるページヘッダーに同じタイトルを使用してください。MCP アプリレポートでは、mcp-app-report.md に従ってください。
• タイトルまたはエグゼクティブサマリーを、ラベルのないサブタイトル、リード、スコープ行、または2つ目のサマリーブロックで重複させないでください。
• レポートタイトルとエグゼクティブサマリーは、別々の表示要素として扱ってください。レポートタイトルは成果物レベルの名前であり、エグゼクティブサマリーセクションの役割を満たすものではありません。ステークホルダー向けレポートでは、タイトルの直後、サマリー内容の前に、表示される Executive Summary セクション見出しをレンダリングしてください。
• ステークホルダー向けレポートは、ユーザーの質問に直接答えるエグゼクティブサマリーで始めてください。デフォルトでは、太字のトピック文を伴う2〜4個の箇条書きまたは短いミニ段落を使用します。
• テクニカルレポートは、主要な結果を述べるテクニカルサマリーで始め、その後、それを信頼するために必要な定義、手法、不確実性、限界を示してください。
• 主要なレポートセグメントは、前置きの文章ではなく、要点から始めてください。一般的なラベルをコピーするのではなく、洞察を伝える見出しを使用してください。
• すべての提供モードで、主要なレポートセグメントごとに表示されるタイトルを含めてください。タイトルは、単なる非公開のメタデータではなく、読者向けレポート契約の一部です。HTML レポートでは、タイトルをセクション内の見出し要素としてレンダリングしてください。MCP アプリレポートでは、mcp-app-report.md に従ってください。エビデンスが裏付ける場合は、「API ARR is pulling ahead of plan」のようなストーリー固有のタイトルを使用し、一般的なラベルは避けてください。
• レポートが上から下へ明確に読める流れを保ってください。ユーザーがダッシュボードを求めていない限り、レポートをダッシュボードグリッドにしてはいけません。デフォルトでは単一カラムのドキュメントフローを使用し、半幅のビジュアルブロックは、選択したサーフェスでラベル、系列、解釈が読める場合にのみ許容されます。
• ナラティブな洞察と解釈には、レポートの markdown ブロックを使用してください。独立してレイアウトされる、または編集可能な主要レポートセグメントごとに、それぞれ独自の markdown ブロックを与えてください。複数の同階層の ## セクション見出しを1つの markdown 本文に置かないでください。### 見出しは、同じカード内に留めるべき下位コンテンツにのみ使用してください。チャート/テーブルのヘッダーは中立的に保ち、主張をビジュアルのメタデータの中に隠すのではなく、隣接するナラティブブロックに要点を置いてください。markdown ブロックはストーリーの主要な場所です。
• レポートは、それ単体で成立するのに十分な内容であるべきです。短いサマリーを伴う、ほとんどがチャート/テーブルの束であるレポートを提供しないでください。読者は、ナラティブ自体から、答え、エビデンス、解釈、注意事項、推奨される次のステップを理解できるべきです。
• 柔軟なセクション名とストーリー固有の順序を使用してください。ただし、レポートが引き続き核心的な役割を果たすようにしてください。ユーザーの質問に直接答えること。解釈に影響する場合は、指標、コホート、分母、時間枠、比較基準を説明すること。各重要な数値またはビジュアルに平易な英語の解釈を添えること。その発見が意思決定にとってなぜ重要かを説明すること。何が依然として不確実であるか、または結論を変えうるかを述べること。エビデンスが裏付ける場合は、実用的な次のステップを含めること。
• エグゼクティブサマリー以外でも、スキャンしやすさが向上する場合は豊富な markdown を使用してください。重要な本文段落ではトピック文を太字にし、推奨事項は実際の markdown リストとして保ち、リスト項目を長く続く段落に押し込まないでください。
• 順序付きまたは順序なしリストを使用する場合は、各項目をそれぞれ独自の Markdown 行に置いてください。1.、2.、3. の項目を同じ段落に置かず、意図したリスト項目を番号なしの継続行として残さないでください。
• エグゼクティブレポート、戦略レポート、診断レポートでは、タイトルの後の最初のナラティブコンテンツはエグゼクティブサマリーであるべきです。サマリーの前に、ラベルのないリード、重複するサマリー、方法論ブロック、注意事項セクション、KPI ストリップ、またはメトリクスカード行を挿入しないでください。
• 診断レポートと戦略レポートでは、エグゼクティブサマリーの前にデフォルトの KPI カード行を挿入しないでください。KPI、ポートフォリオ、MBR/QBR、および領域ごとに1セクションのレポートでは、ヘッドラインの実績値、差分、ステータスシグナルが利用可能な場合、サマリーの後にコンパクトな KPI カードストリップを使用してもかまいません。
• KPI、ポートフォリオ、または複数領域のレポートで、主要なサマリー成果物としてエグゼクティブサマリーの直下に広範な比較テーブルを使用しないでください。ヘッドラインの実績値、差分、ステータスシグナルが利用可能な場合は、ざっと見て把握できるトップラインのステータスにメトリクスカードを使用し、正確な値を裏付ける場合や監査の詳細にはテーブルを使用してください。
• メトリクスカードには1つのヘッドライン値を含めるべきですが、1つのヘッドラインは1つの metrics[] エントリを意味するものではありません。そのヘッドラインに直接結び付く短い比較コンテキスト、たとえば前期の値、目標、差分には、ラベル付きチップを使用してください。意思決定に関連する方向性のある比較がすでにエグゼクティブサマリーまたは調査結果で使用されている場合は、それを後続の比較メトリクスとして保持し、signed: true を設定してください。独立した二次指標は、別のカード、チャート、テーブル、またはナラティブブロックに移してください。
• ヘッドラインのメトリクスカードの数は、レポートの意思決定によって決めてください。セットを4つ、または任意の好ましい数に埋めたり切り詰めたりしないでください。明確で意味のあるヘッドライン指標のみを含め、一貫性のあるカードを同じストリップにグループ化し、無関係な指標は別のストリップまたは補足テーブルに分けてください。成果物レンダラーは行をレスポンシブにバランス調整するため、奇数個でも有効です。
• パーセント値は、選択したサーフェスで一貫した数値スケールを使用する必要があります。
• 主要なレポートセグメントはすべて、主張とエビデンスおよび解釈を組み合わせ、次に含意、リスク、機会、推奨事項、監視ポイント、または次のアクションで「だから何なのか」に答えてください。
• エビデンスがアクションを裏付ける場合は、推奨される次のステップを含めてください。エビデンスが監視のみを裏付ける場合は、何をなぜ監視すべきかを述べてください。
• 意味のある不確実性、不足しているエビデンス、またはフォローアップ分析が意思決定を変えうる場合は、さらなる質問を含めてください。意思決定に関連する未解決の質問がない場合にのみ、このセクションを省略し、その選択をソースノートに記録してください。
• 注意事項と不確実性は、答えを圧迫することなく、解釈を変える場所で可視化するべきです。

エビデンスと出典

• 主要な主張はすべて、タスク中に保存、作成、または確認したデータ、コード、クエリ結果、ノートブックの出力、ソース文書、レンダリング済みのチャートに基づけてください。
• 選択した表示面で対応している場合、重要な数値、チャート、推奨事項は、関連する段落やビジュアルの近くに読みやすいソースメタデータを付けてください。
• 生のパス、ノートブックの場所、一時ディレクトリ、リクエスト ID、実装向けの監査情報は、信頼性のために必要な場合を除き、ソースメタデータ、ソースノート、または補足資料に記載してください。HTML レポートでは、HTML Report Specifications で必要とされるソースツールチップにソースシステム名とテーブル名を表示し、信頼性のために必要な場合を除き、常に表示される説明文には含めないでください。
• ソース SQL は、ソースメタデータ、ソースモーダル、リンクされたクエリアーティファクト、または補足ノートに記載してください。ユーザーが SQL やクエリ手法の表示、作成、レビュー、デバッグ、または受け取りを明示的に求めた場合を除き、表示されるレポート本文や最終チャットの引き継ぎにソース SQL を貼り付けないでください。
• ユーザーが手法の説明を明示的に求めた場合を除き、画面下部に出典、注記、再現手順のセクションを表示しないでください。
• レポート本文に表示しない場合も、ソースデータセット、クエリまたは変換アーティファクト、レンダリングコード、出力フォルダー、前提条件、省略した指標、チャートの QA ノートは、ソースメタデータ、ソースノート、または補足資料に残してください。
• 監査に十分なエビデンスへのアクセス手段を用意しつつ、表示される主張のグラフが煩雑にならないようにしてください。対応している場合は、ブロック単位のソース参照を優先してください。

ビジュアルと表

• レポートのビジュアルの見出しは中立的なものにしてください。グラフ／表の名前に、指標、分母、コホート、フィルター、または期間を明確にする必要がある場合に限り、短い説明を添えます。ナラティブ形式のインサイトや注意点は、隣接する Markdown ブロックに記載してください。
• レポートの各ビジュアライゼーションには、読み進める流れの中で、その直前または直後に説明の段落を配置してください。この段落では、要点、ビジュアルの読み方、解釈に必要な示唆や注意点を説明します。グラフのタイトル、副題、キャプション、指標カード、表のヘッダーだけでは、この要件を満たしません。
• グラフや表の副題には、タイトルで触れていない、読み手にとって有用なインサイトや解釈の背景を加えてください。たとえば、傾向、規模、変曲点、順位、比較の基準、対象範囲、期間、測定単位、フィルター／除外条件、分母、コホート、サンプルサイズ、比較の基準などを示します。例：4月中旬以降に成長が加速し、期間中の最高値で終了、FY2021-FY2024、単位：百万米ドル。説明や副題は、読み進め方を明確にするために showDescription または同等のフラグが必要な場合を除き、デフォルトでは非表示にしてください。
• 表示する Markdown、グラフのタイトル／副題、キャプション、表のラベル、生成日の表示では、人が読みやすい日付を優先してください。ISO タイムスタンプは、クエリのバインディング、ソースメタデータ、その他の機械可読フィールドで使用してください。
• ソースのテーブル名、クエリの生 ID、ダッシュボードのスラッグ、ノートブックのパス、SQL の意図、指標の定義、実装上のラベルを、グラフ／表の副題に使用しないでください。ソースの識別情報が読み手の信頼に不可欠な場合を除き、これらの情報はソースメタデータ、ソースノート、または補足資料に記載してください。HTML レポートでは、ソースシステム名とテーブル名も、関連する数値またはグラフのソースツールチップに表示してください。副題を煩雑にせず、必要なときに確認できるようにします。
• レポートの表を描画する前に、すべての表の副題を表のタイトルおよび表示される列と照らし合わせて確認してください。対象となる行、対象期間、値の測定方法、適用されるフィルター、または比較内容が明確にならない副題は、書き換えるか省略してください。ソース名で代用しないでください。
• ビジュアルを、読みにくい小さなサイドカードに縮小しないでください。情報量の多いグラフ、長いラベル、またはより広いスペースを必要とする HTML グラフの代替表示には、全幅のブロックを使用してください。
• レポートのグラフは、最終的な文脈で確認して読みやすさが保たれる場合を除き、読み進める流れの中で独立した、見やすい行またはブロックに配置してください。レポートの根拠を示すグラフに、幅の狭い右側レールのカードを使用しないでください。
• レポートのトレンドグラフには、傾向を読み取る価値があるだけの観測データを含めてください。レポートのグラフが少数の基準期間しか示さない場合は、描画前に $visualize-data を再度実行して、より細かい粒度、より長い対象期間、または意味のあるセグメント分解を指定してください。読み手に誤解を与えずにソースからデータを取得できない場合は、トレンドグラフを KPI ストリップ、期間ごとの集合棒グラフ、表、または簡潔なナラティブ形式の比較に置き換え、より詳細なトレンドを省略したことをソースノートまたは補足資料に記録してください。
• レポートの表では、行数が少なく、ナラティブ形式でプレゼンテーションに適した表には、ゆとりのある密度をデフォルトとして使用してください。高密度の表は、監査／詳細表やコンパクトな参照データに限って使用してください。
• 表の正負の色分けは、movement: true、semantic: "movement"、または role: "movement" が明示された列に限って使用してください。これらの列の値には、+12%、-$4.2M、↑3 pp、-18 のように、意図した符号または矢印を付けてください。構成比、ミックス、シェア、パーセンタイル、現在値の列は中立的な色にしてください。
• 複数のグラフを含むレポートでは、簡潔なグラフマップをソースノートまたは補足資料に記載してください。各ビジュアルについて、レポートのセグメント、分析上の問い、選択したファミリー／タイプ、フィールド、裏付けとなる主張を明記します。同じグラフタイプを繰り返す場合は、その理由を示してください。レポートの各セグメントで問う内容がステータス、構成、差異、要因、分布など異なるにもかかわらず、すべてのビジュアルにトレンドグラフを使用するのは避けてください。
• レポートをエクスポートまたは変換する場合、インタラクティブなビジュアルやサーフェス固有のビジュアルはすべて、読みやすい静的な表現も用意してください。静的な表現がない、または誤解を招く場合は、ブロッカーとして記録してください。

指標と言語

• 実装の詳細を示す前に、指標を平易な英語で説明します。
• レポートで指標に依拠する前に、定義、コホート、分母、フィルター、比較基準を明確にします。
• ユーザー、アカウント、ワークスペース、タスク、ターン、セッション、リクエスト、売上、エンドポイント、顧客、組織、その他のビジネス上の単位から、オーディエンスにとって最も解釈しやすい粒度を選びます。
• 生の数値は、アクティブな母集団に占める割合、ファネルの前段階に対する割合、変化全体に占める割合、ベースラインとの比較、目標、同業セグメント、過去の範囲などを使って文脈に位置づけます。
• 説明文、グラフのラベル、要約では、899k、10.9k、1.2M のような大きな数値の略記を使用します。カンマ区切りの正確な値は、監査用テーブル、SQL 出力、付録、または精度が解釈を左右する場合に限って使用します。
• 信頼性の確保に不可欠な場合を除き、実装向けのイベント名、フィールド名、テーブル名、厳密な述語は本文から除外します。注意事項、ソースメタデータ、または短い括弧書きに記載します。
• 選択したオーディエンスに合わせて最終的な文面を整えます。簡潔で、結論を先に述べ、作業過程に関する注記を含めず、結果を信頼するために必要な範囲を超えて手法を詳述しません。

品質基準

最終版を引き渡す前に、以下を確認します。

• 以下の必須項目に不備がある場合は、レポートを修正するか、最終化する前に未解決の阻害要因を明記します。
• ユーザーがハイブリッド形式または第 2 の提供形式を明示的に求めた場合を除き、提供形式はちょうど 1 つ、オーディエンスの指定もちょうど 1 つを使用します。
• 選択したオーディエンス仕様の Required Structure が、表示されるレポートの各セクションに対応していることを確認します。統合、名称変更、順序変更、省略があれば、ソースノートまたは補足資料に記録します。
• レポートの骨子、レポート深度の判断基準、選択した提供形式の仕様、レンダリング後のレポートをすべて確認します。
• レンダリング後のレポートがユーザーの質問に直接答え、読者に伝わるセグメントタイトルを表示し、主要な主張それぞれに根拠、解釈、必要に応じた注意事項、意思決定に役立つ示唆を添えていることを確認します。
• 定義、分母、ベースライン、要求された指標、注意事項を明確にしてから、最終的な主張を意思決定に使えるものとして扱います。省略した指標には理由を示し、必要なフォローアップを記載します。
• 手法の詳しさが選択したオーディエンスに合っていることを確認します。また、省略した要求指標について、その理由と必要なフォローアップを説明します。
• ビジュアルとテーブルが $visualize-data を通じて作成され、選択した表示環境で確認されていることを確認します。また、各ビジュアルに、読みやすさ、有用なサブタイトル、隣接する説明段落、ソースメタデータ、補足ノートが備わっていることを確認します。
• HTML レポート内のソースに裏付けられた定量値すべてに、正常に機能するホバーおよびキーボードフォーカス対応のソースツールチップがあることを確認します。また、すべての静的グラフ図にも同等のツールチップがあり、正確なソースシステムと、テーブル、ビュー、データセット、ファイル、またはドキュメントの出所が示されていることを確認します。
• ソースと再現性に関する注記、グラフマップ、省略理由は、表示されるレポートを煩雑にしないよう、メタデータ、ソースノート、または補足資料に保持します。
• 最終的な引き渡しでは、選択したレポート成果物と関連する根拠資料を列挙します。チャット上の要約で代用したり、依頼されていない並行アプリと HTML レポートの両方を提出したりしません。