okhp3-outcome-modeling-core

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Build a defensible model for systems where many noisy events contribute to a measurable outcome. The core separates the shared world model from the decision objective, so the same evidence can support forecasting, ranking, budgeting, or market comparison without confusing prediction with optimization.

Scope

| In scope | Out of scope | |----------|-------------| | Repeated event histories, state vectors, and aggregate outcomes | A universal algorithm that fits every dataset | | Feature reduction and diminishing-returns testing | Claims that a fixed feature count always explains 95% of outcomes | | Calibrated forecasts and decision-ready uncertainty | Presenting a forecast as certainty or advice without constraints | | Domain-adapter routing and handoff contracts | Live trading, betting, or political targeting |

Core mental model

Treat a complex system as a noisy, time-indexed process:

text
events -> entity state -> outcome estimate -> objective and constraints -> decision

Aggregation can reduce the relative influence of idiosyncratic noise, but it does not erase causal structure, dependencies, or meaningful rare events. The goal is to expose persistent signal while preserving uncertainty and time order.

Computational payload

Use the formulas, glossary, synthetic fixture, and deterministic helper supplied with this package. Read references/computational-model.md for the event-to-state, logistic, feature-tier, calibration, and decision equations. Read references/glossary.md before using unfamiliar terms. Run scripts/calculate-outcome-model.py examples/core-example.json to reproduce the small arithmetic example. The helper reads local JSON, prints JSON, and performs no network access or writes.

Operating procedure

1. Define the decision before the model

Record:

• target outcome and unit of analysis;
• forecast horizon and as-of timestamp;
• decision owner and action window;
• utility, cost, budget, risk tolerance, and hard constraints;
• whether the task is descriptive, predictive, causal, or allocative.

Do not optimize accuracy by default. A probability forecast, expected value estimate, ranking, and budget allocation are different products.

2. Build the event-to-state representation

Identify the entity, event, relationship, and time grain. Preserve raw observations, sample sizes, missingness, and provenance. Derive an entity state only from information available at the as-of time.

Use a state vector when many observations describe the same entity:

text
state(entity, t) = transformed features available at t

Use an interaction or delta representation when two entities jointly determine an outcome:

text
delta(A, B, t) = state(A, t) - state(B, t)

3. Aggregate at multiple scales

Inspect the smallest meaningful events, then roll them up through the operational hierarchy. Name each aggregation because different scales answer different questions.

text
event -> session or possession -> period -> case or game -> season or cohort

Do not assume aggregation makes outcomes 50/50. It generally stabilizes estimates of persistent effects. Strong asymmetries can remain.

4. Compress features without hiding structure

Create a feature inventory with source, definition, unit, grain, polarity, cadence, missingness, and leakage risk. Group correlated variables under interpretable factors, but retain the raw fields for auditability.

Test nested feature tiers such as 10, 30, 60, 120, and 200 only when the dataset supports them. Compare each tier to a simple baseline using time-aware out-of-sample metrics. Stop adding variables when incremental value is negligible, unstable, or caused by leakage.

5. Validate in time and across entities

• Split by time, not random rows, when future prediction is involved.
• Use as-of joins and lagged rolling features.
• Hold out later periods or entities when generalization matters.
• Compare calibration, log loss, Brier score, ranking quality, and decision value as appropriate.
• Inspect subgroup and segment performance.
• Recheck drift after structural changes, interventions, or regime shifts.

Accuracy alone is insufficient. A model can rank well but be poorly calibrated, or forecast well while producing a bad allocation under costs and constraints.

6. Add causal and intervention checks

If the recommendation changes the system, separate prediction from treatment effect. Ask what would have happened without the action. Use experiments, holdouts, natural experiments, or a clearly labeled observational design when appropriate.

Never infer that a high-performing entity caused its outcome merely because it was associated with it. Check selection bias, confounding, reverse causation, and opportunity assignment.

7. Produce the decision layer

Choose an explicit objective such as:

text
expected outcome
- monetary cost
- capacity cost
- downside risk
+ retention, option, or spillover value

State the optimization rule, constraints, assumptions, and what would change the recommendation. When a market price or benchmark exists, compare independent estimate, implied probability, uncertainty, and transaction or implementation cost.

Output contract

Return, as applicable:

1. objective, target, horizon, and as-of boundary;
2. data and provenance inventory;
3. event-to-state and aggregation ladder;
4. feature groups and excluded or leaky fields;
5. baseline and candidate model comparison;
6. calibration, uncertainty, drift, and subgroup checks;
7. objective function and constraints;
8. ranked options or allocation with rationale;
9. unresolved assumptions and the next validation step.

If required data is absent, produce a model specification and data request rather than invented numbers.

Family routing

Load this skill first, then add the narrowest adapter:

• okhp3-outcome-modeling-sports for team, game, or player outcomes;
• okhp3-nfl-fantasy-picks for NFL fantasy rosters and salary-constrained picks;
• okhp3-outcome-modeling-sales for pipeline, rep, account, and commercial value;
• okhp3-outcome-modeling-markets for prediction-market prices and expected value.

References

• references/computational-model.md -- shared equations and worked example.
• references/glossary.md -- plain-language definitions and abbreviations.
• examples/core-example.json -- synthetic input fixture.
• scripts/calculate-outcome-model.py -- dependency-free local calculator.
• okhp3-outcome-modeling-sports/SKILL.md -- sports state and matchup adapter.
• okhp3-nfl-fantasy-picks/SKILL.md -- NFL fantasy decision adapter.
• okhp3-outcome-modeling-sales/SKILL.md -- commercial value and sales adapter.
• okhp3-outcome-modeling-markets/SKILL.md -- market-price and risk adapter.

About

Built by Jamie Hill · OverKill Hill P³ Published at github.com/OKHP3 Part of the OKHP3/skillz Agent Skill library. MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.