weekly-performance-digest

Weekly Performance Digest

概要

Weekly Performance Digest は、1 週間に決済したトレードを 1 つのパフォーマンスレポートにまとめます。trader-memory-core が追跡する決済済みのトレード仮説（state/theses/th_*.yaml）を読み込み、主要な指標（勝率、期待値、プロフィットファクター、R 倍数、MAE／MFE）を計算します。さらに、複数のパターンの観点（ソーススキル、決済理由、トレード仮説の種類、セクター、メカニズムタグ、スクリーニング評価）で結果を分類し、その週の最大の勝ちトレード、負けトレード、学びを提示します。出力は JSON レコードと、人が読める Markdown レポートです。計算のみを行うため、API キーは不要です。

使用する場面

• 取引週の終わりに、実現したパフォーマンスの全体像を振り返る場合
• 決済済みの全ポジションを対象に、勝率と期待値を測定する場合
• 勝ち負けを左右したソーススキル、決済理由、セクター、メカニズムを確認する場合
• 月末レビュー（週次ダイジェスト 4 件をまとめる）や事後分析に活用する場合
• 実際に決済したトレードに基づいて、「何がうまくいき、何がうまくいかなかったか」を手早く把握する場合

使用しない場面

• 1 件のトレードを詳細に振り返る場合 — trade-performance-coach を使用してください
• シグナルを真陽性／偽陽性に分類する場合 — signal-postmortem を使用してください
• 売買の推奨やポジションサイズの算出 — このスキルは記述的な分析のみを行います

前提条件

• PyYAML を含む Python 3.9 以降（すでにリポジトリの依存関係に含まれています）
• トレード仮説の YAML ファイルが格納された trader-memory-core の状態ディレクトリ（state/theses/）
• API キーは不要です

ワークフロー

ステップ 1：対象週のダイジェストを実行する

python3 skills/weekly-performance-digest/scripts/generate_weekly_digest.py \
  --state-dir state/theses \
  --from-date 2026-06-13 --to-date 2026-06-20 \
  --output-dir reports/ -v

デフォルト値は、--state-dir state/theses、--from-date は --to-date の 7 日前、--to-date は今日、--output-dir reports/ です。日付フラグを指定しない場合は、直近 7 日間のダイジェストを作成します。

ステップ 2：レポートを読む

実行すると、reports/weekly_digest_<to-date>.json と reports/weekly_digest_<to-date>.md が生成されます。Markdown でエグゼクティブサマリー、指標テーブル、パターン別の分類、上位の勝ちトレード／負けトレードを確認し、JSON を後続処理に使用してください。

ステップ 3（任意）：後続処理に渡す

複数の週次 JSON ダイジェストをまとめて月次レビューを行うか、JSON を事後分析／コーチングのステップに渡します。このスキルは記述的な分析を行うため、分析結果に基づく対応は通常のレビュープロセスを通じて行ってください。

仕組み

• トレードの選定。 exit.actual_date が [from-date, to-date] の範囲内で、status == CLOSED の場合、そのトレードは対象週に含まれます。
• 勝ち／負け。 outcome.pnl_dollars > 0 は勝ち、< 0 は負け、== 0 は損益なしです。win_rate = winners / total_trades です。
• R 倍数。 pnl_dollars / ((entry.actual_price − exit.stop_loss) × position.shares) です。（実際のトレード仮説スキーマに従い、ストップロスは exit.stop_loss から読み取ります。）
• 二重計上の防止。 CLOSED のトレード仮説の outcome.pnl_dollars は、すべての部分決済と最終決済を含む累積実現損益です。主要指標では、CLOSED のトレード仮説のみを対象にこの累積値を使用します。別途設けられた partial_trims ブロックは、まだオープン状態の PARTIALLY_CLOSED のトレード仮説のみを対象に status_history[] を調べ、参考情報として報告します。主要な合計値や勝率には決して加算されません。そのため、1 週目に一部を決済し、2 週目に全決済したポジションは、1 週目には部分決済として、2 週目には CLOSED の主要指標に含まれます。これは意図した動作であり、二重計上ではありません。

出力形式

JSON（weekly_digest_<to-date>.json）

{
  "schema_version": "1.0",
  "report_type": "weekly_performance_digest",
  "period": {"from": "2026-06-13", "to": "2026-06-20"},
  "generated_at": "2026-06-20T21:39:07Z",
  "summary": {
    "total_trades": 2, "winners": 1, "losers": 1, "breakeven": 0,
    "win_rate": 0.5, "expectancy": 25.0, "profit_factor": 2.0,
    "total_realized_pnl": 50.0, "total_realized_pnl_pct": 4.17
  },
  "metrics": {
    "avg_winner": 100.0, "avg_loser": -50.0,
    "largest_winner": 100.0, "largest_loser": -50.0,
    "avg_holding_days_winners": 9.0, "avg_holding_days_losers": 6.0,
    "r_multiple_avg": 0.25, "r_multiple_stdev": 1.06,
    "avg_mae_pct": -3.75, "avg_mfe_pct": 4.5
  },
  "pattern_analysis": {
    "by_source_skill": {"...": {"wins": 1, "losses": 0, "total": 1, "win_rate": 1.0}},
    "by_exit_reason": {}, "by_thesis_type": {}, "by_sector": {},
    "by_mechanism_tag": {}, "by_screening_grade": {}
  },
  "partial_trims": {"count": 0, "total_realized_pnl": 0.0, "trims": []},
  "lessons": {"top_wins": [], "top_losses": [], "process_improvements": []}
}

Markdown（weekly_digest_<to-date>.md）

セクション：# Weekly Performance Digest、## Executive Summary、## Performance Metrics、## Pattern Analysis、## Lessons Learned（### Top Winners／### Top Losers／### Process Improvements）。

対象週にトレードがなくても、指標がすべて 0 の有効なレポートが生成されます（終了コード 0）。

リソース

• scripts/generate_weekly_digest.py — ダイジェスト生成スクリプト（JSON + Markdown）
• references/weekly-digest-metrics.md — 指標の計算式と解釈

主な原則

1. ヘッドラインの数値には決済済みの取引のみを使用 — 累積的なoutcome.*を決済日に基づいて集計します。
2. 二重計上しない — 一部利確は参考情報として記録し、合計からは除外します。
3. パターンへの帰属 — すべての勝ち負けを複数の側面に分類します。
4. 記述的であり、指示的ではない — ダイジェストが報告し、判断するのはあなたです。