ecom

ecom — Eコマース事業レビュー ツールキット

D2C Eコマースの分析です。付属の Python エンジンが注文取引データから KPI を計算し、健全性チェックを実行して、パフォーマンスを評価します。その後、あなた（Claude）が数値を解釈し、人が読めるレポートを作成します。

重要な原則： 数値の計算は Python が行い、解釈は Claude が行います。 ビジネス上の背景を示さずに、生の数値を提示してはいけません。

引数： $ARGUMENTS（空の場合は会話の内容から意図を推測します）

モードの選択

引数／意図	モード	出力
空、または review	フルレビュー（データから期間を自動選択）	REVIEW.md
review 30d ／ 90d ／ 365d	フルレビュー、単一期間	REVIEW_{PERIOD}.md
自然言語の質問を含む	フォーカスクエリ	インライン回答、ファイルなし

入力

注文取引 CSV。各行は 1 件の注文または明細項目です。 必須列：注文 ID、注文日、顧客 ID（またはメールアドレス）、売上 （割引適用後、税・送料適用前）。任意列：数量、SKU／商品、 割引額。列名はローダーがあいまい一致で判定します。

CSV が指定されていない場合は、作業ディレクトリ内の *.csv を Glob で検索し、 候補として考えられるファイルが複数ある場合はユーザーに確認します。

エンジンの実行

このプラグインが有効な間、ecom CLI は PATH 上にあります。

ecom review orders.csv --output <output-dir>
ecom review orders.csv --period 90d --output <output-dir>

ecom が PATH 上にない場合は、同じ引数を指定して付属のランチャーを使います："${CLAUDE_SKILL_DIR}/../../bin/ecom"。初回実行時には ~/.local/share/claude-ecom/ の下に専用の Python venv がセットアップされるため、1 分ほどかかる場合があります。2 回目以降の実行はすぐに完了します。

出力：出力ディレクトリ（デフォルトは現在のディレクトリ）に作成される review.json（--period を指定した実行では review_{period}.json）

ワークフロー

フェーズ 1：計算（Python）

エンジンを実行します（モードの選択に応じて --period を追加します）。利用可能な各期間について、前期間との比較を含むサマリー KPI、新規顧客とリピーターに分けた KPI ツリー、売上要因の分解（AOV／販売量／構成）、さらに 365d の場合はリピート購入率と 12 か月分の monthly_trend を計算します。また、売上、顧客、商品に関する約 30 件の健全性チェックを評価します。各チェックは pass ／ watch ／ fail を返し、🟢／🟡／🔴 のマーカーに反映されます。

フェーズ 2：解釈（あなた — Claude）

フルレビュー：

1. review.json を読みます（下記のデータルールを参照。スキーマ全体は review-schema.md を参照）
2. report-format.md を読みます。レポート作成前に必ず読むこと。 すべてのセクションのテンプレートと「調査結果の品質基準」が記載されています。
3. review-narratives.md を読み、 ナラティブの流れを選びます。
4. 必要に応じて、ほかのリファレンスを読み込みます（下表を参照）。
5. 下記のレポート契約を満たす REVIEW.md（または REVIEW_{PERIOD}.md）を作成します。

フォーカスクエリ：

1. focused-query.md を読みます。必読です。 クエリと期間の対応、および回答形式が記載されています。
2. 対応する期間でエンジンを実行し、JSON を読み、インラインで回答します （10～30 行）。ファイルは作成しないでください。

トレンドと診断を織り交ぜ、筋の通った一つのストーリーにまとめることがあなたの役割です。 期間分析は「今後どこに向かっているか」を示し、健全性チェックは 「現在何が問題か」を示します。レポートでは両方を組み合わせます。

レポートの要件（全体レビュー）

執筆前に、レポートに以下のすべてのセクションがこの 順序で含まれていることを確認してください。セクションの欠落や順序の入れ替えは、フォーマット違反です。

1. エグゼクティブサマリー — 物語形式の引用ブロック（4～6行）＋スコアボード表
2. 30日間の動向セクション（データがある場合） — KPIツリー＋所見は最大1件
3. 90日間の勢いセクション（データがある場合） — KPIツリー＋要因＋所見は最大2件
4. 365日間の構造セクション（データがある場合） — KPIツリー＋要因＋所見は最大3件
5. アクションプラン — 期間別にまとめた項目は最大5件＋ガードレール（必須）
6. データに関する注記 — 2～4行

厳守事項：

• 全体を約150行に収め、全期間を通じた所見は最大5～7件とします。同じ所見を複数の期間で繰り返してはいけません。
• セクションの順序を守り、テーマ別に再構成してはいけません。「うまくいっている点」や「対処すべき課題」の独立したセクションは設けません。肯定的なシグナルはエグゼクティブサマリーとKPIツリーのマーカーに記載します。
• すべての期間別セクションで、🟢／🟡／🔴マーカーを使ったKPIツリー形式を用います。
• すべての所見は、何が起きているか → なぜ重要か → 何をすべきかの形式にします（定量的な事実 → データに基づく課題 → 進むべき方向）。「検討する」「改善する」「最適化する」「探る」は使用禁止です。
• アクションプランは、期限と成功指標の唯一の基準とし、最後にガードレール（悪化させてはならない指標を2～3個）を記載します。

テンプレート、例、品質基準の全文は report-format.mdを参照してください。

参照ファイル

必要に応じて読み込みます。起動時にすべて読み込んではいけません。パスはこの スキルのディレクトリからの相対パスです。

ファイル	読み込むタイミング
report-format.md	毎回の全体レビューで、執筆前に読み込みます
review-narratives.md	毎回の全体レビューで読み込みます。健全度と推移に応じた物語の展開を確認します
focused-query.md	毎回の焦点を絞った問い合わせで読み込みます
review-schema.md	review.jsonの意味が不明確な場合に読み込みます
finding-clusters.md	全体レビューで読み込みます。関連する課題をテーマごとにまとめる際に使用します
recommended-actions.md	要注意／不合格のチェック項目をアクションに変換する際に読み込みます
impact-formulas.md	売上への影響を見積もる際に読み込みます
health-checks.md	チェック項目の定義やしきい値が不明確な場合に読み込みます
benchmarks.md	KPIをD2Cベンチマークと比較する際に読み込みます

データのルール

• review.jsonのみを使用します。 すべての数値はreview.jsonに含まれる値、またはその値から導出したものでなければなりません。外部ソース（Shopify Analytics、GAなど）を参照してはいけません。外部調査をアクションとして提案することはできますが、その数値を引用してはいけません。
• periodsには、data_coverageでtrueになっている期間のみが含まれます。すべての_changeフィールドは前の期間との比率です（0.08 = +8%）。
• health.top_issuesは不合格のチェック項目を事前に並べ替えたものです。action_candidatesはPythonによる提案です。これらを業務で使われる表現に整え、書き直してください。原文をそのままコピーしてはいけません。
• レポート内で内部チェックIDやチェック件数を明かしてはいけません。
• data_qualityが空でない場合は、関連する警告をデータに関する注記に記載し、月の一部期間のみの前月比を実際のパフォーマンスシグナルとして示してはいけません。

データが不完全な場合

• 測定できない内容は省略します。「該当なし」、空のセクション、謝罪は不要です。
• データが少ない場合は、レポートも短くします。データの欠落については、データに関する注記にのみ記載します。

言語

データに関する注記を含むレポート全体を、単一の言語で記述します。ユーザーのプロンプト／ストアの言語に合わせます。

品質基準

• 数値を解釈なしで提示してはいけません。必ずその理由を説明します。
• 専門用語ではなく、業務で使う表現を用います。用語は初出時に説明します。
• 関連する所見を結び付け、体系的な傾向を示します。
• 80/20の法則を守ります。約80％は確認事項（信頼を築く）、約20％は新たな発見（行動を促す）とします。
• 数値スコア、文字による評価、健全度の割合評価は禁止します。合格／要注意／不合格のシグナルのみ使用します。