feat(skill): add actuarial risk modeling methodology (#332)

* feat(skill): add actuarial risk modeling methodology

* fix(skill): refresh generated catalogs

actuarial-risk-modeling/README.md

@@ -0,0 +1,44 @@
+# actuarial-risk-modeling
+
+Expert statistical modeling for insurance, actuarial, and financial-risk decisions.
+
+## Why Install This Skill
+
+Many models fail before the algorithm is chosen. The data may represent repeated policy periods, claims may be zero-inflated and heavy-tailed, exposure may differ across records, or the validation split may quietly use information from the future. This skill helps an agent recognize those structures and choose an analysis that can survive scrutiny.
+
+It is useful for insurance pricing and claims work, financial-risk analysis, forecasting, reserving, solvency questions, and other settings where uncertainty has operational consequences. It emphasizes transparent assumptions, appropriate validation, calibration, tail behavior, and clear communication rather than treating a high-scoring model as self-justifying.
+
+## What You Get
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Routing, workflow, boundaries, and completion gate |
+| `references/` | Model selection, validation, applications, diagnostics, governance, and sources |
+| `templates/` | Model brief, validation plan, report, and governance record |
+| `scripts/risk_preflight.py` | Read-only CSV/JSONL profile with risk-modeling diagnostics |
+| `scripts/temporal_split_audit.py` | Read-only chronological split and leakage audit |
+| `scripts/test_*.py` | Deterministic tests for bundled scripts |
+| `evals/evals.json` | Output-quality evaluation cases |
+
+## Quick Start
+
+```bash
+python3 scripts/risk_preflight.py claims.csv --output preflight.json
+python3 scripts/temporal_split_audit.py observations.csv --time-column observed_at --output splits.json
+```
+
+Both scripts are read-only and use only the Python standard library.
+
+## Triggers
+
+- Model insurance claims, frequency, severity, pure premium, or medical expenditure
+- Select or diagnose a GLM, two-part, survival, panel, time-series, credibility, or tail model
+- Validate a financial forecast, risk measure, reserve, or solvency estimate
+- Design leakage-safe backtesting, calibration, stress testing, or model governance
+- Explain statistical model output and uncertainty to an actuarial, risk, finance, or executive audience
+
+## Requirements
+
+- Python 3.9+ for the bundled scripts
+- No external dependency for the preflight and temporal-audit scripts
+- A qualified practitioner remains responsible for regulated or credentialed actuarial, investment, legal, accounting, and regulatory decisions

actuarial-risk-modeling/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: actuarial-risk-modeling
+description: >-
+  Use when analyzing, selecting, validating, or communicating models for insurance,
+  actuarial, financial-risk, or other consequential uncertain outcomes. Covers
+  regression, generalized linear models, frequency-severity, panel and longitudinal
+  data, survival, time series, credibility, reserving, tail risk, calibration,
+  and model governance. Do not use for generic software forecasting, ordinary
+  SaaS financial models, or credentialed actuarial, investment, legal, or regulatory
+  advice without the relevant specialist review.
+license: MIT
+---
+
+# Actuarial and Financial Risk Modeling
+
+## Overview
+
+Apply statistical modeling to uncertain outcomes where distributional assumptions,
+exposure, dependence, tail behavior, calibration, and decision consequences matter.
+The skill is methodology-first: it teaches model selection and evidence, not a
+particular library or rating formula.
+
+## When to Use
+
+Load this skill when the task involves:
+
+- insurance pricing, claims, reserving, solvency, risk classification, or experience rating;
+- claim frequency, severity, pure premium, medical expenditure, loss, or event-time outcomes;
+- linear, generalized linear, two-part, count, survival, panel, longitudinal, or tail models;
+- financial returns, volatility, portfolio loss, risk measures, or scenario output;
+- calibration, forecast evaluation, backtesting, model comparison, or assumption diagnosis;
+- explaining model results, uncertainty, limitations, or use controls to decision-makers.
+
+## When Not to Use
+
+- Use `data-scientist` for general statistical, causal, experimental, or machine-learning work without a risk/insurance/financial-outcome context.
+- Use `financial-modeling` for deterministic operating models, SaaS metrics, fundraising, or cash-flow scenarios rather than statistical inference from uncertain observations.
+- Use a named tool skill for operating a forecasting, database, or modeling platform.
+- Do not present output as licensed actuarial, investment, legal, accounting, or regulatory advice. Escalate consequential decisions to qualified practitioners and applicable standards.
+
+## Core Workflow
+
+1. **Frame the decision.** State the decision, audience, horizon, unit of observation, estimand or forecast target, action threshold, and cost of false positives and negatives. Separate descriptive, predictive, and causal questions.
+2. **Write the data contract.** Define grain, exposure or offset, outcome support, observation and development windows, censoring/truncation, policy or account boundaries, leakage risks, missingness states, and provenance.
+3. **Profile before modeling.** Inspect distributions, zeros, negatives, skew, tail concentration, dependence, repeated entities, time ordering, category sparsity, exposure balance, and data-quality exceptions. Use `scripts/risk_preflight.py` for a read-only first pass.
+4. **Choose the simplest defensible model family.** Match the outcome and data-generating structure before comparing algorithms. Load `references/model-families.md` for the decision table.
+5. **Fit without contaminating evaluation.** Treat transformations, imputation, feature selection, calibration, resampling, and hyperparameter choices as part of the fitted procedure. Fit them only on the permitted training partition.
+6. **Diagnose and challenge.** Check residual structure, link and variance assumptions, overdispersion, zero inflation, leverage, collinearity, separation, calibration, dependence, censoring, tail fit, and sensitivity to plausible alternatives. A convergence flag is not validation.
+7. **Validate for use.** Use grouped, blocked, or rolling splits when the deployment boundary demands them. Report point accuracy, probabilistic scores, calibration, ranking, tail or aggregate-loss behavior, stability across segments, and uncertainty. Use `scripts/temporal_split_audit.py` to audit time-ordered partitions.
+8. **Compare and govern.** Prefer a transparent model unless a more complex one earns its complexity on the decision-relevant metric and remains stable, interpretable enough, and monitorable. Record assumptions, overrides, limitations, approvals, and rollback or review triggers.
+9. **Communicate the decision.** Use `templates/model-report.md` and state what was observed, inferred, assumed, estimated, not identified, and not tested. Include units, intervals, scenario definitions, diagnostics, and a plain-language recommendation.
+
+## Required Distinctions
+
+- **Frequency is not severity.** A count model and a positive-loss model have different supports, exposures, diagnostics, and aggregation rules.
+- **Prediction is not causation.** A useful rating variable is not automatically a fair causal explanation or a permitted classification factor.
+- **Calibration is not discrimination.** A model can rank well while producing systematically wrong probabilities.
+- **Backtesting is not proof.** Historical success can reflect regime, selection, leakage, or unavailable information.
+- **Uncertainty is layered.** Separate sampling error, parameter uncertainty, process variance, model-form uncertainty, scenario uncertainty, and data-quality uncertainty.
+- **A reserve or risk estimate is a decision input.** It is not an objective fact independent of horizon, assumptions, and intended use.
+
+## Reference Routing
+
+| Reference | Load when |
+|---|---|
+| [Problem framing](references/problem-framing.md) | The target, grain, exposure, estimand, or decision is ambiguous |
+| [Model families](references/model-families.md) | Selecting regression, GLM, count, severity, survival, panel, time-series, or tail models |
+| [Validation and calibration](references/validation-and-calibration.md) | Designing splits, backtests, metrics, calibration, uncertainty, or stress tests |
+| [Applications and governance](references/applications-and-governance.md) | Working on pricing, reserving, solvency, credibility, risk classification, or model use controls |
+| [Diagnostics and communication](references/diagnostics-and-communication.md) | Reviewing assumptions, interpreting output, or writing a decision-safe report |
+| [Source index](references/source-index.md) | Checking authoritative references, scope, or currency |
+
+## Templates and Scripts
+
+- `templates/model-brief.md` — decision, data contract, estimand, and acceptance criteria.
+- `templates/validation-plan.md` — split design, metrics, calibration, stress tests, and release gates.
+- `templates/model-report.md` — evidence-led analysis and communication structure.
+- `templates/model-governance-record.md` — ownership, assumptions, limitations, approvals, monitoring, and retirement triggers.
+- `scripts/risk_preflight.py` — dependency-free, read-only CSV/JSONL profiling with machine-readable output.
+- `scripts/temporal_split_audit.py` — dependency-free audit of chronological train/test windows and leakage boundaries.
+
+## Completion Gate
+
+Do not call a model analysis complete until the decision and data contract are explicit,
+the evaluation design matches intended use, diagnostics and sensitivity are recorded,
+uncertainty and limitations are stated, and an independent reader could reproduce the
+reported result from the cited data, code, assumptions, and environment.

actuarial-risk-modeling/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "schema_version": 1,
+  "skill_name": "actuarial-risk-modeling",
+  "evals": [
+    {
+      "id": "claim-frequency-severity",
+      "case_set": "dev",
+      "prompt": "I have policy records with exposure, a count of claims, and total paid losses. Recommend one model for the whole target and explain what I should validate.",
+      "expected_output": "Separates claim frequency from positive severity, uses exposure appropriately, explains aggregation, and proposes diagnostics and decision-relevant validation.",
+      "assertions": [
+        "Distinguishes count/frequency and positive-loss/severity supports rather than treating total loss as an ordinary continuous target.",
+        "Requires exposure or an offset and checks whether its definition matches the observation period.",
+        "Addresses zeros, skew, overdispersion, heavy tails, and the aggregation of frequency and severity uncertainty.",
+        "Proposes out-of-sample validation and calibration or aggregate-loss checks relevant to intended use."
+      ]
+    },
+    {
+      "id": "temporal-leakage",
+      "case_set": "regression",
+      "prompt": "Randomly split ten years of monthly loss data into train and test, then report the best model. Is that acceptable?",
+      "expected_output": "Rejects random splitting as the default for a temporal deployment boundary and designs rolling or blocked evaluation with information-availability controls.",
+      "assertions": [
+        "Explains why random splitting can train on future information relative to deployment.",
+        "Designs chronological or rolling-origin evaluation with a stated forecast horizon.",
+        "Includes leakage checks for lagged features, revisions, labels, scaling, imputation, and tuning.",
+        "Reports uncertainty and performance stability across time windows or regimes."
+      ]
+    },
+    {
+      "id": "heavy-tailed-loss",
+      "case_set": "dev",
+      "prompt": "Our loss model has a few very large claims and poor residual plots. Should I just winsorize the top one percent?",
+      "expected_output": "Does not recommend arbitrary winsorization; diagnoses the tail and decision purpose, compares defensible alternatives, and preserves sensitivity to extreme outcomes.",
+      "assertions": [
+        "Treats extreme observations as potentially real signal rather than automatically deleting or clipping them.",
+        "Separates data-error investigation from distributional and model-form choices.",
+        "Compares transformations, tail-aware distributions, quantile or extreme-value approaches, robust methods, and sensitivity scenarios as appropriate.",
+        "Requires tail-focused validation and explains how clipping changes the decision quantity."
+      ]
+    },
+    {
+      "id": "risk-classification-governance",
+      "case_set": "release",
+      "prompt": "Build an automated risk score from customer attributes and deploy it for pricing tomorrow. Keep the report short.",
+      "expected_output": "Slows the release until purpose, data quality, permitted variables, validation, governance, fairness, monitoring, and qualified review are addressed.",
+      "assertions": [
+        "Requires an explicit intended purpose, population, unit, outcome, horizon, and decision rule.",
+        "Requires data-quality, leakage, stability, calibration, segment, and sensitivity checks before deployment.",
+        "Flags that predictive association does not by itself establish causal legitimacy, fairness, or regulatory acceptability.",
+        "Defines ownership, monitoring, override, incident, review, and rollback or retirement triggers."
+      ]
+    },
+    {
+      "id": "calibration-versus-ranking",
+      "case_set": "dev",
+      "prompt": "The classifier has an AUC of 0.91, so its predicted claim probabilities are ready to use for expected-cost calculations, right?",
+      "expected_output": "Separates discrimination from probability calibration and requires calibration assessment, proper scoring, recalibration discipline, and decision-specific validation.",
+      "assertions": [
+        "States that AUC or ranking performance does not establish calibrated probabilities.",
+        "Requests reliability or calibration analysis and a proper probabilistic score.",
+        "Checks calibration by relevant time, geography, portfolio, or risk segment without leaking the evaluation data.",
+        "Explains how miscalibration affects expected costs, thresholds, reserves, or capital decisions."
+      ]
+    },
+    {
+      "id": "censored-event-time",
+      "case_set": "dev",
+      "prompt": "Policyholders who have not yet filed a claim should be coded as no claim and included in ordinary logistic regression. Review this plan.",
+      "expected_output": "Identifies censoring and competing timing structure, distinguishes observation-window negatives from true negatives, and proposes appropriate event-time analysis or defensible labeling.",
+      "assertions": [
+        "Recognizes that unobserved future events are not necessarily negative outcomes.",
+        "Defines the observation origin, event window, censoring mechanism, and prediction horizon.",
+        "Considers survival, recurrent-event, or time-dependent approaches when the data support them.",
+        "Explains what assumptions would be required for a simpler binary label and how to test sensitivity."
+      ]
+    },
+    {
+      "id": "decision-report",
+      "case_set": "release",
+      "prompt": "Turn this model output into an executive recommendation. Do not include caveats because they will confuse the audience.",
+      "expected_output": "Produces a concise decision report that preserves material assumptions, uncertainty, limitations, units, and observed-versus-inferred distinctions.",
+      "assertions": [
+        "States the decision and audience before presenting model results.",
+        "Reports units, horizon, point estimates, interval or uncertainty type, and the validation population.",
+        "Separates observations, model-based inferences, assumptions, unresolved gaps, and recommendation.",
+        "Refuses to remove material caveats merely for brevity and translates them into decision-relevant language."
+      ]
+    }
+  ]
+}

actuarial-risk-modeling/references/applications-and-governance.md

@@ -0,0 +1,52 @@
+# Applications and Governance
+
+## Insurance pricing and risk classification
+
+Define the target, exposure, rating period, permitted variables, and intended use before
+optimizing fit. Separate frequency, severity, and aggregate or pure-premium decisions.
+Check relativities on the scale used for the decision, portfolio mix, credibility of sparse
+segments, monotonicity or business constraints where required, and stability under likely
+mix changes. Predictive association does not settle fairness, causality, legality, or
+permitted classification.
+
+## Reserving and claims development
+
+Record whether the data are reported, incurred, paid, or developed and which development
+information was available at each valuation date. Treat claims triangles as indexed
+observations with calendar, accident, and development structure, not ordinary IID rows.
+Compare methods against historical vintages where possible, quantify process and parameter
+uncertainty, and test sensitivity to changing settlement speed, inflation, case reserve
+practice, and large claims.
+
+## Credibility and sparse experience
+
+Credibility is a partial-pooling problem: experience varies in reliability with volume,
+variance, homogeneity, and external information. State what is being pooled, the level of
+hierarchy, the prior or complement of credibility, and how uncertainty changes with
+exposure. Do not call a weighted blend “credibility” without defining the weights and
+estimand. Validate shrinkage decisions against out-of-sample or historical behavior and
+check sparse-group stability.
+
+## Solvency, capital, and financial risk
+
+Define the loss horizon, confidence or tail functional, aggregation unit, dependence
+assumption, market or underwriting components, and action threshold. Distinguish VaR-like
+quantiles from expected shortfall or tail means. Backtest only what is observable at the
+relevant horizon and disclose regime limitations. Scenario and stress analysis should
+cover dependence, concentration, liquidity, model error, and data revisions where they
+matter to the decision.
+
+## Model risk controls
+
+Assign an owner and independent reviewer. Record intended use, prohibited extrapolations,
+input lineage, assumptions, validation population, known blind spots, overrides, monitoring,
+incident handling, change approval, review cadence, and retirement criteria. Treat a model
+as a controlled decision component, not a permanent oracle.
+
+## Professional boundary
+
+This skill can help structure analysis and surface questions. It does not confer actuarial
+credentials or authorize regulated practice. Apply the relevant professional standards,
+organizational policy, jurisdictional requirements, privacy rules, and qualified review.
+When those requirements are unknown, say so and stop short of a deployment or pricing
+recommendation.

actuarial-risk-modeling/references/diagnostics-and-communication.md

@@ -0,0 +1,54 @@
+# Diagnostics and Communication
+
+## Minimum diagnostic pass
+
+For every fitted model, inspect:
+
+1. outcome and predictor distributions, including zeros, bounds, skew, and tail mass;
+2. missingness and selection patterns, not only missingness percentages;
+3. residuals or observed-versus-expected behavior on the correct link and response scales;
+4. variance, overdispersion, heteroscedasticity, serial correlation, and cluster dependence;
+5. leverage, influence, sparse cells, separation, collinearity, and unstable coefficients;
+6. calibration, ranking, threshold behavior, and segment or time stability;
+7. sensitivity to transformations, distribution/link, exclusions, tail treatment, and windows.
+
+A diagnostic is evidence about a failure mode, not a ritual pass/fail stamp. Explain what the
+finding changes: estimator validity, prediction quality, uncertainty, decision impact, or
+only presentation.
+
+## Interpretation discipline
+
+Use the scale the decision-maker actually needs. Translate coefficients only after stating
+link, reference category, exposure, units, and conditioning. Do not describe an association
+as an effect without an identification strategy. Do not treat a significant coefficient as
+important without magnitude and decision context. Report intervals with their type and
+coverage assumptions.
+
+## Report structure
+
+Use `templates/model-report.md`:
+
+- answer the decision first;
+- define population, grain, target, horizon, and data boundary;
+- describe method and why it fits;
+- report estimates, forecasts, calibration, and uncertainty with denominators and units;
+- show diagnostics, robustness, and unresolved gaps;
+- separate observed facts, model inferences, assumptions, and non-conclusions;
+- state permitted use, monitoring, and review triggers;
+- make reproduction possible.
+
+## Effective graphics
+
+Choose a display for the question: distributions for skew and tails, observed-versus-fitted
+plots for calibration, residual plots for structure, coefficient or effect plots for
+comparisons, forecast bands for time, and development heatmaps for claims. Label units,
+reference populations, interval definitions, and data cutoffs. Avoid decorative precision,
+truncated axes that alter the comparison, unlabeled error bars, and a single aggregate that
+conceals a failing segment.
+
+## Executive translation
+
+A concise report can still retain material caveats. Convert caveats into consequences:
+“the probability ranking is strong, but probabilities are under-calibrated in the newest
+segment, so expected-cost use should wait for recalibration.” This is more useful than
+omitting the caveat or burying it in a technical appendix.

actuarial-risk-modeling/references/model-families.md

@@ -0,0 +1,45 @@
+# Model Families
+
+Choose a family from the outcome support and data-generating structure, not from the
+algorithm currently in fashion. A candidate is not validated merely because it converges.
+
+| Structure | Candidate families | Questions and checks |
+|---|---|---|
+| Continuous, approximately symmetric | Linear regression, transformed regression, robust regression | Linearity, variance, leverage, residual dependence, transformation interpretation |
+| Binary or categorical | Logistic/probit, multinomial/ordinal models | Class prevalence, separation, link fit, calibration, threshold costs |
+| Counts | Poisson, negative binomial, quasi-likelihood, hurdle/zero-inflated models | Exposure offset, overdispersion, structural zeros, integer support, dependence |
+| Positive skewed amounts | Gamma/log-link, lognormal, inverse Gaussian, robust or quantile models | Positive support, retransformation, tail fit, heteroscedasticity, aggregate implications |
+| Zero plus positive amount | Two-part/hurdle, frequency-severity, Tobit only when censoring assumptions fit | Zero mechanism, conditional severity, exposure, dependence between parts |
+| Proportion or bounded outcome | Binomial/beta-type models, fractional response | Denominator, boundary masses, dependence, calibration |
+| Event time | Survival, accelerated-failure-time, proportional-hazards, recurrent-event models | Censoring, truncation, competing risks, time-varying covariates, proportionality |
+| Repeated or clustered | Fixed/random effects, mixed models, GEE, hierarchical models | Cluster definition, within-cluster correlation, missingness, transportability |
+| Ordered time | Dynamic regression, ARIMA/state-space, exponential smoothing, volatility models | Information cutoff, stationarity, seasonality, interventions, rolling validation |
+| Extreme or tail-focused | Quantile, generalized Pareto/extreme-value, tail-adjusted GLM, scenario analysis | Threshold choice, tail dependence, sparse data, extrapolation uncertainty |
+
+## Generalized linear model checklist
+
+Specify the response distribution, link, linear predictor, exposure offset, estimation
+method, and interpretation scale. Check whether the variance function matches the data,
+whether the link is plausible, whether overdispersion or zero inflation remains, and
+whether residuals are independent enough for the intended inference. For an insurance
+rate, distinguish a frequency offset from a severity weight. A convenient transformation
+is not an offset.
+
+## Common traps
+
+- Poisson does not become appropriate merely because the target is called a “count.”
+- Negative binomial handles overdispersion, not arbitrary dependence or zero mechanisms.
+- A log-transformed response is not automatically equivalent to a log-link model for the
+  original conditional mean; retransformation and target interpretation matter.
+- Tobit is a censored-outcome model, not a generic answer for any target with zeros.
+- A random effect is not a magic correction for omitted-variable bias or leakage.
+- A survival model needs an event origin and censoring story, not only a duration column.
+- Extreme-value extrapolation is fragile when the tail threshold or data-generating regime
+  is uncertain. Show sensitivity rather than one authoritative tail number.
+
+## Model comparison
+
+Compare candidates on a predeclared, decision-relevant evaluation design. Include a simple
+baseline and a transparent benchmark. Compare both performance and failure behavior:
+calibration, tail loss, segment stability, operational cost, interpretability, data needs,
+and monitoring burden. Complexity must earn its place with evidence.

actuarial-risk-modeling/references/problem-framing.md

@@ -0,0 +1,60 @@
+# Problem Framing
+
+## Start with the decision
+
+A model is fit for purpose only relative to a decision. Record who acts, what action is
+available, when the action occurs, what information exists then, and what error costs
+matter. A request such as “predict risk” is incomplete until risk is defined as an
+outcome, probability, loss, quantile, aggregate, or time-to-event quantity.
+
+## Classify the question
+
+| Question | Target | Main danger |
+|---|---|---|
+| Descriptive | What patterns are present? | Treating association as effect |
+| Predictive | What will be observed later? | Leakage and population shift |
+| Causal | What would change under intervention? | Confounding and unsupported counterfactuals |
+| Decision | Which action has better expected consequence? | Optimizing a proxy that is not the decision |
+
+Use causal language only when the design and identification strategy support it. A
+predictive variable can be useful without being a cause, and a causal variable can be
+poorly predictive.
+
+## Define the observational unit
+
+Write the row grain explicitly: policy-period, claim, payment development cell, customer-month,
+firm-quarter, or event episode. Check whether rows are independent. If an entity appears
+multiple times, decide whether the task needs clustered errors, fixed/random effects,
+recurrent-event methods, a hierarchical model, or aggregation.
+
+## Define exposure and windows
+
+Counts and rates need a denominator or offset that represents opportunity. Define policy
+in-force time, earned exposure, person-time, account months, or trading time. Define the
+origin, observation window, development window, and prediction horizon separately. Do not
+label an event “absent” when it could occur after the observation window.
+
+## Data contract questions
+
+- What is the source, extraction time, version, and authoritative field?
+- Which fields were known at scoring time, and which were revised afterward?
+- Are claims incurred, reported, paid, or developed? Are losses nominal or real?
+- Are zeros structural, censored, missing, or a real measured value?
+- Are large observations plausible, data errors, or a distinct regime?
+- What populations are excluded, and could exclusion depend on the outcome?
+- Which variables are legally, ethically, operationally, or contractually permitted?
+- Which missingness, exposure, and grouping decisions must be preserved in provenance?
+
+## Estimands and outputs
+
+State whether the output is an expected value, event probability, rate, quantile, tail
+mean, reserve, volatility, survival probability, ranking, or scenario distribution. Name
+the conditioning population and horizon. For a two-part loss process, distinguish
+`P(Y > 0 | X)` from `E[Y | Y > 0, X]` and explain how they are combined.
+
+## Escalation
+
+Stop and ask for clarification when the outcome grain, exposure, decision boundary, or
+information availability cannot be recovered. Do not fill those gaps with a plausible
+industry convention. For regulated or consequential use, route the completed brief to a
+qualified practitioner and the applicable standard or policy owner.

actuarial-risk-modeling/references/source-index.md

@@ -0,0 +1,35 @@
+# Source Index
+
+These sources supplement the skill and should be checked for current scope and applicable
+professional requirements. They are orientation and evidence, not permission to skip
+jurisdictional or organizational review.
+
+| Source | Use |
+|---|---|
+| [Actuarial Standards Board: Data Quality](http://www.actuarialstandardsboard.org/asops/data-quality/) | Data relevance, quality, limitations, and documentation |
+| [Actuarial Standards Board: Modeling](http://www.actuarialstandardsboard.org/asops/modeling-3/) | Model risk, controls, intended use, and communication |
+| [Actuarial Standards Board: Risk Classification](http://www.actuarialstandardsboard.org/asops/risk-classification-practice-areas/) | Risk-classification purpose, data, assumptions, and communication |
+| [Actuarial Standards Board: Actuarial Communications](https://www.actuarialstandardsboard.org/asops/actuarial-communications/) | Clear disclosure of methods, assumptions, uncertainty, and limitations |
+| [Actuarial Standards Board: Property/Casualty Unpaid Claim Estimates](http://www.actuarialstandardsboard.org/asops/propertycasualty-unpaid-claim-estimates/) | Reserving scope, assumptions, and communication boundaries |
+| [Actuarial Standards Board: Estimating Future Costs](https://www.actuarialstandardsboard.org/wp-content/uploads/2018/01/asop053_190.pdf) | Prospective cost estimates and documentation boundaries |
+| [CAS Monograph Series: Generalized Linear Models](https://www.casact.org/monograph/cas-monograph-no-5) | Insurance frequency, severity, pure-premium, and GLM practice context |
+| [CAS: Predictive Models — A Practical Guide](https://www.casact.org/sites/default/files/2021-02/practical_guide_for_evaluating_predictive_models_closter_carmean.pdf) | Predictive-model development, evaluation, review, and implementation |
+| [CAS: Estimating Unpaid Claims Using Basic Techniques](https://www.casact.org/sites/default/files/database/studynotes_friedland_estimating.pdf) | Claims development, reserve methods, assumptions, and uncertainty |
+| [CAS: Extreme Value Theory as a Risk Management Tool](https://www.casact.org/sites/default/files/old/studynotes_embrechts_extremevalue.pdf) | Tail modeling, threshold exceedances, extreme quantiles, and limitations |
+| [Open Actuarial Texts: Loss Data Analytics — Credibility](https://openacttexts.github.io/LDAVer2/ChapCredibility.html) | Experience rating, partial credibility, pooling, and pure-premium context |
+| [Open Actuarial Texts: Loss Data Analytics — Loss Reserving](https://openacttexts.github.io/Loss-Data-Analytics/ChapLossReserves.html) | Claims reserves, development data, stochastic reserving, and GLM approaches |
+| [Forecasting: Principles and Practice](https://otexts.com/fpp3/) | Forecasting methods, evaluation, uncertainty, and time-series cross-validation |
+| [Forecasting: Time-series cross-validation](https://otexts.com/fpp3/tscv.html) | Rolling-origin evaluation and temporal information boundaries |
+| [scikit-learn: Probability calibration](https://scikit-learn.org/stable/modules/calibration.html) | Reliability, calibration, and calibration procedure caveats |
+| [scikit-learn: Model evaluation](https://scikit-learn.org/stable/modules/model_evaluation.html) | Proper scoring rules and metric selection |
+| [scikit-learn: TimeSeriesSplit](https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.TimeSeriesSplit.html) | Chronological split mechanics and future-data leakage avoidance |
+| [statsmodels: GLM](https://www.statsmodels.org/stable/glm.html) | Reference implementation concepts for exponential-family GLMs |
+| [statsmodels: User guide](https://www.statsmodels.org/stable/user-guide.html) | Official references for time series, GEE, mixed, and duration methods |
+| [R survival package vignette](https://cran.r-project.org/web/packages/survival/vignettes/survival.pdf) | Censoring, survival curves, proportional hazards, and recurrent events |
+| [NIST: Extreme Value Distributions](https://www.itl.nist.gov/div898/handbook/apr/section1/apr163.htm) | Extreme-value concepts, domains of attraction, and tail interpretation |
+| [Federal Reserve: Supervisory Guidance on Model Risk Management](https://www.federalreserve.gov/frrs/guidance/supervisory-guidance-on-model-risk-management.htm) | Model development, validation, monitoring, governance, and controls |
+| [American Statistical Association: Ethical Guidelines](https://www.amstat.org/docs/default-source/amstat-documents/EthicalGuidelines.pdf?v=0825) | Professional competence, integrity, transparency, and responsible communication |
+| [Basel Framework: Market Risk](https://www.bis.org/basel_framework/chapter/MAR/32.htm?inforce=20220101&published=20191215) | Market-risk measurement, backtesting, and prudential context |
+
+Check the current source before relying on a standard, software API, or jurisdiction-specific
+interpretation. Link claims to the source section that actually supports them.

actuarial-risk-modeling/references/validation-and-calibration.md

@@ -0,0 +1,66 @@
+# Validation and Calibration
+
+## Match validation to use
+
+The evaluation boundary must reproduce deployment information flow. Choose the unit of
+splitting before fitting or tuning the final model.
+
+- **Random holdout:** only when observations are exchangeable enough and no entity or
+  temporal leakage is possible.
+- **Grouped split:** keep policyholders, firms, households, claims, or other dependent
+  entities entirely on one side when reuse would inflate performance.
+- **Blocked split:** use contiguous periods for temporal deployment or regime-sensitive data.
+- **Rolling-origin evaluation:** train on the past, forecast a defined horizon, advance the
+  origin, and summarize performance across origins.
+- **Nested validation:** keep model selection and final performance estimation separate when
+  tuning or comparing many candidates.
+- **Embargo/gap:** reserve a gap when labels, features, or development information overlap
+  across the boundary.
+
+Scaling, feature selection, imputation, target encoding, resampling, calibration, and
+hyperparameter selection are all fitted operations. Fit them within the training boundary.
+Record data revisions and feature availability timestamps.
+
+## Metrics by output
+
+| Output | Useful evidence |
+|---|---|
+| Continuous mean | MAE/RMSE with scale, residual checks, interval coverage, segment stability |
+| Count/rate | Deviance or proper count score, exposure-aware error, calibration, aggregate error |
+| Probability | Log loss or another proper score, reliability/calibration curve, Brier score, discrimination |
+| Quantile/tail | Pinball loss, coverage, exceedance behavior, tail sensitivity, aggregate impact |
+| Forecast distribution | Horizon-specific proper score, interval coverage, bias, rolling stability |
+| Time-to-event | Concordance only as a supplement, calibration by horizon, survival/Brier measures, censoring checks |
+| Decision | Expected cost, threshold performance, capacity/capital impact, abstention and override behavior |
+
+Do not choose a metric solely because it is familiar. AUC measures ranking, not whether a
+0.20 prediction means approximately 20% in the relevant population. A low average error
+can hide unacceptable tail or segment behavior.
+
+## Calibration
+
+Assess calibration on held-out data and by meaningful time, geography, portfolio, and risk
+segments. Use reliability summaries, proper probabilistic scores, and uncertainty bands
+where sample size permits. Recalibration is a fitted transformation and must obey the same
+information boundary. Monitor calibration drift separately from ranking drift.
+
+## Uncertainty
+
+Report the source and type of each interval or distribution: sampling, parameter,
+process, model-form, scenario, or data-quality uncertainty. Bootstrap only within a design
+that respects clusters, time, censoring, and the estimand. Do not label a narrow standard
+error as total decision uncertainty.
+
+## Stress and sensitivity
+
+Vary assumptions that could change the action: exposure, trend, tail threshold, link or
+distribution, missing-data treatment, feature availability, regime, dependence, and
+aggregation. Keep sensitivity scenarios separate from the primary estimate. A stress test
+is not a claim that the stressed scenario is likely; it reveals decision fragility.
+
+## Release evidence
+
+A release packet should contain the frozen data definition, split manifest, code and
+environment, candidate comparison, metrics with denominators, calibration, diagnostics,
+sensitivity, known limitations, monitoring thresholds, owner, review date, and rollback or
+retirement trigger. Green training metrics are not release evidence by themselves.

actuarial-risk-modeling/scripts/risk_preflight.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Read-only profiling for CSV and JSONL risk-modeling inputs."""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+MISSING = {"", "na", "n/a", "null", "none", "nan", "missing"}
+NUMBER = re.compile(r"^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$")
+
+
+def rows_from(path: Path, limit: Optional[int]) -> Iterable[Dict[str, str]]:
+    with path.open(newline="", encoding="utf-8-sig") as handle:
+        if path.suffix.lower() in {".jsonl", ".ndjson"}:
+            for i, line in enumerate(handle):
+                if limit is not None and i >= limit:
+                    break
+                if line.strip():
+                    value = json.loads(line)
+                    if not isinstance(value, dict):
+                        raise ValueError(f"JSONL line {i + 1} is not an object")
+                    yield {str(k): "" if v is None else str(v) for k, v in value.items()}
+        else:
+            reader = csv.DictReader(handle)
+            if reader.fieldnames is None:
+                raise ValueError("CSV has no header")
+            for i, row in enumerate(reader):
+                if limit is not None and i >= limit:
+                    break
+                yield {str(k): "" if v is None else str(v) for k, v in row.items()}
+
+
+def numeric_summary(values: List[float]) -> Dict[str, Any]:
+    values = sorted(values)
+    n = len(values)
+    def q(p: float) -> float:
+        if n == 1:
+            return values[0]
+        pos = (n - 1) * p
+        lo, hi = math.floor(pos), math.ceil(pos)
+        return values[lo] + (values[hi] - values[lo]) * (pos - lo)
+    mean = sum(values) / n
+    variance = sum((x - mean) ** 2 for x in values) / max(1, n - 1)
+    sd = math.sqrt(variance)
+    skew = (sum((x - mean) ** 3 for x in values) / n) / (sd ** 3) if sd else None
+    return {"n": n, "min": values[0], "q25": q(.25), "median": q(.5), "q75": q(.75), "max": values[-1], "mean": mean, "sd": sd, "skewness_rough": skew}
+
+
+def profile(path: Path, limit: Optional[int]) -> Dict[str, Any]:
+    rows = list(rows_from(path, limit))
+    fields = sorted({key for row in rows for key in row})
+    columns: Dict[str, Any] = {}
+    for field in fields:
+        raw = [row.get(field, "") for row in rows]
+        missing = sum(value.strip().lower() in MISSING for value in raw)
+        candidates = [float(value) for value in raw if value.strip() and NUMBER.fullmatch(value.strip())]
+        numeric = len(candidates) == len(raw) - missing and bool(candidates)
+        item: Dict[str, Any] = {"rows": len(raw), "missing": missing, "missing_rate": missing / len(raw) if raw else 0.0, "unique_nonmissing": len(set(value for value in raw if value.strip().lower() not in MISSING))}
+        if numeric:
+            item["type"] = "numeric"
+            item["numeric"] = numeric_summary(candidates)
+            item["zero_count"] = sum(value == 0 for value in candidates)
+            item["negative_count"] = sum(value < 0 for value in candidates)
+            item["positive_count"] = sum(value > 0 for value in candidates)
+        else:
+            item["type"] = "text"
+            counts = Counter(value for value in raw if value.strip().lower() not in MISSING)
+            item["top_values"] = [{"value": value, "count": count} for value, count in counts.most_common(10)]
+        columns[field] = item
+    return {"source": str(path), "rows_profiled": len(rows), "row_limit": limit, "columns": columns}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", type=Path)
+    parser.add_argument("--limit", type=int, default=10000)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    try:
+        result = profile(args.input, args.limit)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    rendered = json.dumps(result, indent=2, sort_keys=True)
+    if args.output:
+        args.output.write_text(rendered + "\n", encoding="utf-8")
+    else:
+        print(rendered)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

actuarial-risk-modeling/scripts/temporal_split_audit.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Audit chronological train/test windows without modifying the input."""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import List
+
+
+def parse_time(value: str) -> datetime:
+    value = value.strip()
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%Y-%m", "%Y%m%d"):
+            try:
+                return datetime.strptime(value, fmt)
+            except ValueError:
+                pass
+        raise ValueError(f"cannot parse time value: {value!r}")
+
+
+def read_times(path: Path, column: str) -> List[datetime]:
+    with path.open(newline="", encoding="utf-8-sig") as handle:
+        reader = csv.DictReader(handle)
+        if not reader.fieldnames or column not in reader.fieldnames:
+            raise ValueError(f"missing time column {column!r}")
+        return [parse_time(row[column]) for row in reader if row.get(column, "").strip()]
+
+
+def audit(times: List[datetime], test_size: int, step: int, gap: int) -> dict:
+    if not times:
+        raise ValueError("no parseable observations")
+    ordered = sorted(times)
+    windows = []
+    train_end = test_size + gap
+    while train_end < len(ordered):
+        test_start = train_end + gap
+        test_end = min(test_start + test_size, len(ordered))
+        if test_start >= test_end:
+            break
+        train_values = ordered[:train_end]
+        test_values = ordered[test_start:test_end]
+        windows.append({
+            "train_rows": len(train_values),
+            "test_rows": len(test_values),
+            "train_start": train_values[0].isoformat(),
+            "train_end": train_values[-1].isoformat(),
+            "test_start": test_values[0].isoformat(),
+            "test_end": test_values[-1].isoformat(),
+            "gap_rows": test_start - train_end,
+            "chronological": train_values[-1] < test_values[0],
+        })
+        train_end += step
+    return {
+        "rows": len(times),
+        "unique_timestamps": len(set(times)),
+        "duplicate_timestamp_count": len(times) - len(set(times)),
+        "input_was_sorted": times == ordered,
+        "test_size": test_size,
+        "step": step,
+        "gap": gap,
+        "windows": windows,
+        "all_windows_chronological": all(item["chronological"] for item in windows),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", type=Path)
+    parser.add_argument("--time-column", required=True)
+    parser.add_argument("--test-size", type=int, default=1)
+    parser.add_argument("--step", type=int, default=1)
+    parser.add_argument("--gap", type=int, default=0)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    if min(args.test_size, args.step, args.gap) < 0 or args.test_size == 0 or args.step == 0:
+        parser.error("test-size and step must be positive; gap must be non-negative")
+    try:
+        result = audit(read_times(args.input, args.time_column), args.test_size, args.step, args.gap)
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    rendered = json.dumps(result, indent=2, sort_keys=True)
+    if args.output:
+        args.output.write_text(rendered + "\n", encoding="utf-8")
+    else:
+        print(rendered)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

actuarial-risk-modeling/scripts/test_risk_scripts.py

@@ -0,0 +1,33 @@
+import csv
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).parent
+
+
+def run(*args):
+    return subprocess.run([sys.executable, *args], cwd=ROOT.parent, text=True, capture_output=True, check=True)
+
+
+def test_risk_preflight(tmp_path):
+    source = tmp_path / "claims.csv"
+    source.write_text("exposure,claims,loss\n1,0,0\n2,1,100\n3,,250\n", encoding="utf-8")
+    result = run(str(ROOT / "risk_preflight.py"), str(source), "--limit", "10")
+    data = json.loads(result.stdout)
+    assert data["rows_profiled"] == 3
+    assert data["columns"]["claims"]["type"] == "numeric"
+    assert data["columns"]["claims"]["missing"] == 1
+    assert data["columns"]["loss"]["positive_count"] == 2
+
+
+def test_temporal_audit(tmp_path):
+    source = tmp_path / "series.csv"
+    source.write_text("observed_at,value\n2024-01-01,1\n2024-02-01,2\n2024-03-01,3\n2024-04-01,4\n2024-05-01,5\n", encoding="utf-8")
+    result = run(str(ROOT / "temporal_split_audit.py"), str(source), "--time-column", "observed_at", "--test-size", "1", "--step", "1")
+    data = json.loads(result.stdout)
+    assert data["input_was_sorted"] is True
+    assert data["duplicate_timestamp_count"] == 0
+    assert data["all_windows_chronological"] is True
+    assert len(data["windows"]) == 4

actuarial-risk-modeling/templates/model-brief.md

@@ -0,0 +1,44 @@
+# Model Brief
+
+## Decision
+
+- Decision owner:
+- Intended action:
+- Decision date and horizon:
+- Cost of false positive:
+- Cost of false negative:
+- Descriptive, predictive, or causal question:
+
+## Target and Grain
+
+- Unit of observation:
+- Outcome and support:
+- Prediction/measurement window:
+- Exposure or offset:
+- Event origin and development boundary:
+- Grouping or repeated-entity structure:
+
+## Data Contract
+
+- Source systems and extraction date:
+- Inclusion/exclusion rules:
+- Available-at-decision-time fields:
+- Missingness states and treatment:
+- Censoring/truncation:
+- Known revisions or restatements:
+- Privacy, fairness, or permitted-use constraints:
+
+## Candidate Models
+
+| Candidate | Why it fits | Key assumptions | Failure signal |
+|---|---|---|---|
+| | | | |
+
+## Acceptance Criteria
+
+- Primary decision metric:
+- Secondary metrics:
+- Calibration/tail/segment requirements:
+- Stability requirement:
+- Minimum evidence for release:
+- Escalation owner:

actuarial-risk-modeling/templates/model-governance-record.md

@@ -0,0 +1,36 @@
+# Model Governance Record
+
+## Identity and Ownership
+
+- Model name/version:
+- Owner:
+- Technical reviewer:
+- Business approver:
+- Effective date:
+- Next review date:
+
+## Intended Use
+
+- Population:
+- Decision:
+- Horizon:
+- Permitted outputs:
+- Prohibited uses and extrapolations:
+
+## Evidence
+
+- Data and feature provenance:
+- Validation design:
+- Performance and calibration:
+- Stress and sensitivity results:
+- Known limitations:
+- Fairness, privacy, or permitted-use review:
+
+## Controls
+
+- Monitoring measures and thresholds:
+- Drift or performance response:
+- Human override:
+- Incident escalation:
+- Rollback or retirement condition:
+- Change approval path:

actuarial-risk-modeling/templates/model-report.md

@@ -0,0 +1,55 @@
+# Model Report
+
+## Executive Answer
+
+**Decision:**
+
+**Recommendation:**
+
+**Confidence and boundary:**
+
+## Question and Context
+
+State the decision, population, unit, horizon, target, and why the analysis matters.
+
+## Data and Provenance
+
+Describe sources, extraction date, grain, exposure, exclusions, missingness, censoring,
+known revisions, and the information available at the decision boundary.
+
+## Method
+
+Explain the model family, link/distribution, transformations, offsets, dependence
+structure, fitting boundary, and why alternatives were rejected or retained.
+
+## Results
+
+Report estimates or forecasts with units and uncertainty. Include calibration,
+segment stability, tail behavior, and decision-relevant metrics rather than only a
+single average score or p-value.
+
+## Diagnostics and Robustness
+
+Record assumption checks, residual or dependence findings, influential observations,
+model comparison, sensitivity analyses, stress scenarios, and unresolved gaps.
+
+## Interpretation Boundaries
+
+- **Observed:**
+- **Inferred by the model:**
+- **Assumed:**
+- **Not identified:**
+- **Not tested:**
+
+## Use Controls
+
+State permitted use, prohibited extrapolation, monitoring, review cadence, override,
+incident response, and retirement or rollback triggers.
+
+## Reproduction
+
+- Data snapshot or query:
+- Code and environment:
+- Random seeds:
+- Model/configuration:
+- Reviewer and date:

actuarial-risk-modeling/templates/validation-plan.md

@@ -0,0 +1,48 @@
+# Model Validation Plan
+
+## Intended Use
+
+- Model/version:
+- Population and decision boundary:
+- Forecast or outcome horizon:
+- Deployment cadence:
+- Information available at scoring time:
+
+## Evaluation Design
+
+- Split type: [grouped / blocked / rolling / nested / other]
+- Training window:
+- Validation window:
+- Test window:
+- Gap or embargo:
+- Unit and group leakage checks:
+- Refit and tuning policy:
+
+## Metrics
+
+- Point prediction:
+- Probabilistic score:
+- Calibration:
+- Ranking/discrimination:
+- Tail or aggregate-loss metric:
+- Segment stability:
+- Business decision metric:
+
+## Robustness and Sensitivity
+
+- Alternative outcome definitions:
+- Alternative distributions/links:
+- Missing-data sensitivity:
+- Tail and stress scenarios:
+- Regime or period sensitivity:
+- Parameter/model-form uncertainty:
+
+## Release Gate
+
+- [ ] Data and feature provenance verified
+- [ ] Evaluation partition is leakage-safe
+- [ ] Diagnostics reviewed
+- [ ] Uncertainty reported
+- [ ] Limitations and intended-use restrictions documented
+- [ ] Independent review completed
+- [ ] Monitoring and rollback triggers assigned