/weekly-performance-digest

name: weekly-performance-digest
description: Generate a weekly performance summary from closed trader-memory-core theses — win rate, expectancy, profit factor, R-multiple, MAE/MFE, and win/loss pattern analysis by source skill, exit reason, thesis type, sector, and mechanism. No API required; pure local calculation.

Weekly Performance Digest

Overview

Weekly Performance Digest aggregates the trades you closed during a week into a single performance report. It reads CLOSED theses tracked by `trader-memory-core` (`state/theses/th_*.yaml`), computes headline metrics (win rate, expectancy, profit factor, R-multiple, MAE/MFE), breaks results down across several pattern dimensions (source skill, exit reason, thesis type, sector, mechanism tag, screening grade), and surfaces the week's biggest winners, losers, and lessons. Output is a JSON record plus a human-readable Markdown report. Pure calculation — no API key required.

When to Use

• At the end of a trading week to review aggregate realized performance
• To measure win rate and expectancy across all closed positions
• To see which source skills, exit reasons, sectors, or mechanisms drove wins vs losses
• To feed a month-end review (combine four weekly digests) or a postmortem
• For a quick "what worked / what didn't" snapshot grounded in real closed trades

When Not to Use

• For a single-trade deep review — use `trade-performance-coach`
• For signal-level true/false-positive classification — use `signal-postmortem`
• For buy/sell recommendations or position sizing — this skill is descriptive only

Prerequisites

• Python 3.9+ with `PyYAML` (already a repo dependency)
• A `trader-memory-core` state directory of thesis YAML files (`state/theses/`)
• No API key required

Workflow

Step 1: Run the digest for a week

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

Defaults: `--state-dir state/theses`, `--from-date` = 7 days before `--to-date`, `--to-date` = today, `--output-dir reports/`. With no date flags it digests the trailing 7 days.

Step 2: Read the report

The run writes `reports/weekly_digest_<to-date>.json` and `reports/weekly_digest_<to-date>.md`. Review the Markdown for the executive summary, metrics table, pattern breakdowns, and top winners/losers; consume the JSON downstream.

Step 3 (optional): Feed downstream

Combine several weekly JSON digests for a monthly review, or pass the JSON to a postmortem/coach step. The skill is descriptive — act on its findings via your normal review process.

How It Works

• **Trade selection.** A trade counts in a week if its `exit.actual_date` falls in

`[from-date, to-date]` and `status == CLOSED`.

• **Win/loss.** `outcome.pnl_dollars > 0` is a winner, `< 0` a loser, `== 0` breakeven;

`win_rate = winners / total_trades`.

• **R-multiple.** `pnl_dollars / ((entry.actual_price − exit.stop_loss) × position.shares)`.

(Stop-loss is read from `exit.stop_loss`, per the real thesis schema.)

• **Double-counting safeguard.** A CLOSED thesis's `outcome.pnl_dollars` is the

*cumulative* realized P&L across all trims plus the final leg. Headline metrics use that cumulative value over CLOSED theses only. The separate `partial_trims` block scans `status_history[]` of **PARTIALLY_CLOSED theses only** (still open) and is reported for information — it is **never** added into the headline totals/win-rate. A position trimmed in week 1 then closed in week 2 therefore shows as a partial trim in week 1 and inside week 2's CLOSED headline; that is intended, not a duplicate.

Output Format

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`)

Sections: `# Weekly Performance Digest`, `## Executive Summary`, `## Performance Metrics`, `## Pattern Analysis`, `## Lessons Learned` (`### Top Winners` / `### Top Losers` / `### Process Improvements`).

An empty week still produces a valid report with zeroed metrics (exit code 0).

Resources

• `scripts/generate_weekly_digest.py` — digest generator (JSON + Markdown)
• `references/weekly-digest-metrics.md` — metric formulas and interpretation

Key Principles

1. **Closed trades only for headline numbers** — cumulative `outcome.*`, keyed on exit date. 2. **No double-counting** — partial trims are informational and excluded from totals. 3. **Pattern attribution** — every win/loss is attributed across multiple dimensions. 4. **Descriptive, not prescriptive** — the digest reports; you decide.