Risk Judgment — public boundary

What this skill protects

The bwmacro/RiskModels stack centralizes risk interpretation (turning raw ERM3 outputs into qualified, PM-readable language) into a single engine that lives privately in BWMACRO. RiskModels_API is the public layer — data, math, chart primitives — and must not contain the editorial vocabulary that the engine produces.

If you are about to write a string like:

• "Strong Residual Alpha", "Solid Residual Quality", "Muted", …
• "performance is beta-driven", "returns are driven by idiosyncratic exposure", …
• "ranks near the top of the cohort", "sits near the cohort median", …
• "High Systematic Exposure", "Underperforming SMH", …

… STOP. That is editorial vocabulary. It belongs in BWMACRO, not here.

When this skill applies

• Any change to a snapshot renderer (sdk/riskmodels/snapshots/*.py).
• Any change to API route handlers under app/api/ that surface

natural-language descriptions of risk.

• Any change to MCP tools that return "interpreted" output.
• Any new feature that classifies a stock or portfolio into a state

(driver = systematic / balanced / idiosyncratic, quality = strong / solid / muted, etc.).

The contract — public side (this repo)

The single public surface for interpretation in this repo is sdk/riskmodels/interpretation.py. It exports:

Snapshot render entry points accept an optional judgment parameter:

def render_dd_to_pdf(data, output_path, *, judgment: Judgment | None = None): ...
def render_dd_to_png(data, output_path, *, judgment: Judgment | None = None): ...
def render_dd_to_png_bytes(data, *, judgment: Judgment | None = None): ...

When judgment is None, the legacy in-SDK editorial generator runs (temporarily, until Phase 1B replaces it with a BWMACRO call site). When provided, the renderer reads judgment.text for headline + insight strings.

The contract — private side (BWMACRO)

The editorial engine lives at:

BWMACRO/bwmacro/risk_interpretation/
  ├── dd.py              # derive_judgment(data) for DD snapshots
  ├── states.py          # threshold tables → discrete states
  ├── flags.py           # predicate flags
  ├── renderers.py       # qualifier vocabulary + PM phrasing
  └── tests/             # eval cases

It imports Judgment, compute_features, and INTERPRETER_VERSION from riskmodels.interpretation and produces a fully-populated Judgment (with states, flags, and editorial text) that the API route layer injects into render_dd_to_* calls.

Rules (non-negotiable)

1. No qualifier vocabulary in this repo. "Strong", "Solid",

"Muted", "beta-driven", "ranks above the median" — all of those go to BWMACRO.

1. No threshold tables in this repo. If you find yourself writing

if residual_share > 0.5: to decide on language, that logic belongs in BWMACRO/bwmacro/risk_interpretation/states.py.

1. No flag predicates in this repo. "high_residual_negative",

"industry_tailwind", etc. live in BWMACRO.

1. `compute_features` is the canonical feature extractor. Do not

re-implement feature extraction inside snapshot renderers. Call compute_features(data) and read from the returned dict.

1. `Judgment` is the canonical interpretation object. API

responses, chat agents, snapshot renderers — all consume the same shape. Do not invent parallel structures.

1. Color = identity, sign = pattern. A negative residual is

green-with-stripes, not red. (See the v9 waterfall fix for context.)

Migration phases (current state: Phase 1A landed)

• Phase 1A (✅ landed): Judgment shape, compute_features, bland

stub, render-entry-point seam. Behavior preserved when judgment=None via the legacy _generate_dd_insights function in sdk/riskmodels/snapshots/stock_deep_dive.py.

• Phase 1B (BWMACRO PR, blocked on 1A): port the body of

_generate_dd_insights to bwmacro/risk_interpretation/dd.py. Add the engine-owner SKILL in BWMACRO. Wire API route handlers to call BWMACRO and inject the result.

• Phase 1C (BWMACRO PR, blocked on 1B): Dagster job — monthly

full-deployment render of top-N tickers, push to GCS at gs://rm_api_data/snapshots/dd/{YYYY-MM}/{ticker}.pdf. API serves from GCS with on-demand fallback for tickers not in the latest batch.

• Phase 2 (RiskModels_API, after 1B): flip the judgment=None

default path to call derive_default_judgment (the bland stub) instead of _generate_dd_insights. Delete the legacy function. SDK community gets bland numeric output; BWMACRO callers get the rich editorial version.

No mock data — paired rule

When real data is missing for a chart panel, API response, or chat output: look in Funds_DAG/data/sync/funds/*.json, the per-fund ds_*.zarr stores, and the RiskModels SDK / API endpoints (use riskmodels-api-discovery first). If the fetcher genuinely isn't wired yet, render an explicit "data unavailable" placeholder and add a backlog entry. Do not synthesize plausible values — even with a watermark; screenshots crop watermarks. Cross-repo full directive: BWMACRO/.cursor/skills/no-mock-data/SKILL.md.

Tracking

The MASTER_BACKLOG entry for this initiative is at BWMACRO/docs/ceo/MASTER_BACKLOG.md under "Risk Interpretation Engine".

Sister boundary — Snapshot composition (PR 3, 2026-05)

A second cross-repo split governs which snapshot layouts ship public vs private. Same shape as the interpretation boundary above, different axis:

Hard rule: the rm_api_public GCS bucket pipeline (bulk_dd_render.py + app/api/snapshot/[ticker]) *never imports `bwmacro.`**. It must stay self-sufficient on the public canonical pipeline. User confirmed this directly during PR 2 and PR 3.

If you need to add a new institutional renderer, put it in BWMACRO and write an adapter in bwmacro/snapshots/stock/adapters.py that maps the private data class onto CanonicalStockSnapshot via riskmodels.snapshots.canonical.from_components.