report-builder

レポートビルダー

オーナーがレポートの内容を一度説明します。レポートを作成して実行し、定義を保存するので、もう一度説明する必要はありません。

オーナーは3つのダッシュボードから手作業で数値を取り出し、自分で傾向を見つけようとしています。この作業をなくすことが目的です。

ステップ 1 — 既存の定義を確認する

何よりも先に、reference/saved_reports.md を読み、このレポートがすでに存在するか確認します。また、作業ディレクトリに report-definitions.md があるかも確認します。スキルフォルダーに書き込めない場合、定義はここに保存されます（ステップ 7 を参照）。

オーナーが「前回と同じレポート」「週次のレポートを実行して」などと言った場合、または定義済みのレポート名を挙げた場合は、ステップ 4 に進んで実行します。すでに定義したレポートについて、もう一度質問するのは、このスキルが壊れていると思わせる最短の方法です。

一致するものがなければ、続けます。

ステップ 2 — 説明を仕様にする

オーナーはレポートを大まかに説明します。「毎週月曜日に、場所ごとの売上を前年と比較して、売掛金の滞留状況と人件費率も出して」といった具合です。この一文には、4つの異なる判断が含まれています。reference/report_spec.md の形式を使って、これらを仕様にまとめます。

• 指標 — それぞれに名前、計算式、データソースを指定
• グループ化 — 場所、商品、顧客、チャネル、担当者別
• 比較 — 前期間比、前年同期比、目標比
• 期間 — 実行ごとに対象とする期間
• 頻度 — 単発、週次、月次、四半期ごと

妥当な範囲で推測します。「場所ごとの売上を前年と比較」からは、指標、グループ化、比較方法がわかります。これらについて質問する必要はありません。本当に曖昧な点だけを、一つずつではなく、まとめて質問します。

ほとんどの場合に確認する価値がある質問は、次の2つです。

• 1回の実行で対象とする期間はどれですか。暦月、直近30日、月初から現在までのいずれですか？
• 「人件費率」のような数値は、売上高に対する比率ですか、それとも総費用に対する比率ですか？

ここを間違えると、見た目は正しいのに実際は間違っているレポートができあがります。それは質問するよりも悪い結果です。

ステップ 3 — 仕様を一度だけ確認する

確定した仕様を簡潔なブロックにまとめて提示します。確認は一度だけ取り、その後作成します。オーナーに仕様の項目を一つずつ説明させないでください。オーナーは一文で説明したのですから、回答も一度で済むと期待しています。

修正があれば反映して、そのまま進めます。再確認はしません。

ステップ 4 — データを取得する

すべてのデータソースへの呼び出しを、一度に並列で実行します。指標とツールの対応については、reference/data_sources.md を参照してください。

次のデータソースを同時に試します。

• 元帳 — 接続されている MYOB、NetSuite、QuickBooks、Xero、Zoho Books のいずれか。コネクター間の扱いについては ../../shared/connector-neutrality.md を参照してください。損益計算書の項目、売上高、費用、売掛金の滞留状況、買掛金、クラス別および場所別の内訳を取得します。MYOB で取得できるのは損益計算書、売掛金、買掛金のみで、対象期間は過去3会計年度です。元帳が2つ接続されている場合は、どちらを正式な記録元とするか確認し、その元帳から合計を取得します
• HubSpot — 取引、ステージ、担当者、成約日、パイプライン金額
• PayPal、Square、Stripe — 入金、手数料、返金、取引の詳細
• Shopify — 注文、SKU 単位の売上、フルフィルメント状況
• Ramp、Expensify — カード支出と経費の詳細。この場合、どちらも読み取り元です。Expensify は読み取り専用の検索に対応しています

データソースでエラーが発生した場合や、何も返されない場合は、その旨を記録して先に進みます。1つのコネクターの問題でレポート全体を止めてはいけません。

コネクターがまったくなくても対応できます。失敗ではありません。 CSV または XLSX のエクスポートを依頼して読み込み、そのファイルから同じレポートを作成します。率直に伝えます。「接続済みのデータソースが見つかりません。お使いのシステムから売上レポートをエクスポートして、ここにアップロードしてください。同じレポートを作成します。」ツールが乱立しているオーナーはこの方法で作業しており、レポートの品質も変わりません。

Step 5 — 計算と妥当性の確認

仕様で指定されたすべての指標を計算します。その後、結果を提示する前に確認してください。実際に起こる失敗パターンについては、reference/gotchas.md を読んでください。

実際のエラーを検出するチェック項目：

• 期間の境界。 当月の途中までの数値を前月の全期間と比較すると、必ず急落したように見えます。同じ条件で比較するか、部分期間であることを明記してください。
• 二重計上。 Shopify の注文と、その Stripe での入金は、1件の売上です。両方のソースが接続されている場合は、売上ソースとしてどちらか一方を選び、どちらを選んだか記載してください。
• 空のグループ。 今期の売上がない拠点も、表示から消すのではなく、ゼロとして表示してください。行が消えると、データの問題だと受け取られます。
• 一致しない合計。 グループごとの行の合計が総計と一致しない場合は、根拠を説明できない数値を公開するのではなく、その不一致を明記してください。

Step 6 — 提出

成果物は必ず次の順序で2つ提出します。

最初にチャットの要約を提示します。 reference/output_template.md に従ってください。表を並べるのではなく、何が変わり、それが何を意味するのかを最初に示します。オーナーがレポートを求めたのは、表計算シートではなく、判断材料が欲しいからです。

このプラグインのすべてのレポートスキルに共通する執筆ルール：

• 数字を先に、言葉を後にします。「売上は好調でした」ではなく、「売上は43,200 USDで、前年同期比8％増でした」とします。
• すべての数値に比較対象を添えます。基準値のない数値は、見落とされた洞察です。
• 例外的な項目を明示します。「結果はまちまちでした」ではなく、「ポートランドは22％減で、前年を下回った唯一の拠点です」とします。
• 要約での所見は最大3件です。それ以外はワークブックに記載します。

次にXLSXを提出します。 指標グループごとに1つのタブを用意し、最初に要約タブ、最後にオーナーが計算を確認できるよう、取得した生データのタブを置きます。手作業ではなく、スクリプトを使って作成してください。

続いて、オーナーが保存した出力設定に従ってレポートページを作成します。Markdownファイルを既定にしてはいけません。 ## Business context ブロックの Output preference を確認してください（共通スタイルガイドのルール、../../shared/artifact-style.md）。

• ビジュアル成果物（既定）： 社内のスタイルに合わせて、レポートをHTMLページとして表示します。各主要指標は比較対象を補足行に示した統計タイルとし、拠点・商品・担当者別などのグループ化された行は、右揃えの等幅数字を使った表にします。目標との比較を含む指標には、ステータスピル（目標達成は良好、未達の兆候は警告、未達は重大）を付けます。冒頭には3件の所見をそれぞれ独立したパネルに配置し、「該当なし」のソースは控えめなフッター1行にまとめます。チャットの要約とワークブックに加えて提出し、どちらの代わりにもしません。
• docx / md / notion / canva の設定： 同じ内容をその形式で提出します。DOCXまたはMarkdownファイル、コネクター経由で作成したNotionページ（指定された保存先に作成し、既存ページを上書きしない）、またはCanvaコネクター経由で作成したCanva Doc（実行ごとに新しいデザインを作成し、日付を付けた名前にする。表はリストに変換）を使います。NotionまたはCanvaが接続されていない場合はビジュアル成果物に切り替え、その理由を伝えてください。XLSXも併せて提出します。
• スキルに最適な形式： ビジュアル成果物を使います。レポートは画面上で読み、週ごとに比較するものです。

Step 7 — 定義を保存

仕様を、作成日と頻度を添えて reference/saved_reports.md に追記します。これにより、レポートを単発ではなく、定期的に作成できるようになります。

このファイルに書き込めない場合（ほとんどのインストール済みランタイムでは、スキルフォルダーは読み取り専用です）、代わりにオーナーの作業ディレクトリにある report-definitions.md に定義を書き込み、保存先を伝えてください。定義の保存に失敗したことを黙っているのは、そもそも保存しないのと同じ不具合です。

オーナーが頻度を指定した場合は、1行で確認します。「保存しました。毎月第1月曜日に実行します。」スケジュール設定はこのスキルの機能であり、別途コマンドは必要ありません。

実行後

1 行で、レポートが実行され、定義が保存されたことを伝えます。続いて、最も関連性の高い次のステップを 1 つ、必要に応じて近くに最大 2 つ添えます。

• 「週次パックを予定どおりに」では、/report-pack を実行して、一定の頻度でこれを状況説明とともにまとめます。
• 「ビジネスの調子はどう？」では、business-pulse を実行して、これらの数値を取り巻く状況を把握します。
• 「キャッシュフロー予測」では、レポートでキャッシュに関する疑問が生じた場合に、cash-flow-snapshot を実行します。

提案は最大 3 つまでです。このセッション中にオーナーが断った提案は、決して繰り返さないでください。

してはいけないこと

• すでに定義済みのレポートについて、オーナーに聞き取りをしないでください。 必ず毎回、最初に saved_reports.md を確認してください。
• データ取得の許可を求めないでください。 スキルは呼び出されています。実行してください。
• 数値を捏造しないでください。 ソースから何も返されなかった場合は、「n/a」と記載し、ソース名を明記してください。オーナーが銀行に転送するレポートに、もっともらしい推測値を載せることは重大な失敗です。
• 表から説明を始めないでください。 主役は要約であり、ワークブックは付録です。
• 「コネクターがない」ことを障害とみなさないでください。 CSV を使う方法も正式な選択肢です。

参照ファイル

• reference/report_spec.md — 作成例を含む仕様の形式
• reference/data_sources.md — フォールバックを含む、指標とコネクターの対応表
• reference/output_template.md — チャットの要約とワークブックの正確な構成
• reference/saved_reports.md — 保存済みのレポート定義。時間の経過とともに追記されます
• reference/gotchas.md — 自信を持って誤ったレポートを作成してしまう原因となる失敗パターン

記載のないツールを使う場合

このスキルに記載されているコネクターは、検証済みの手段であり、利用可能な手段を限定するものではありません。オーナーが、接続されていない、または記載されていないツールをこのワークフローで使いたい場合は、build-connector を提案してください。まずコネクターディレクトリを確認し、それ以外の場合は Zapier 経由で接続します。生の API に対して手作業で構築することはありません。接続が確立されると、そのツールは他の任意のコネクターと同様に、このスキルで同じ承認ゲートのもと利用できるようになります。