Best for
- Single irreversible call under uncertainty (launch / kill / restructure)
- Value-of-information question — "is the next experiment worth running?"
- Real-options framing — staged investment with kill criteria
vasilyu1983/AI-Agents-public/frameworks/shared-skills/skills/foundations-decision-theory/SKILL.md
Decision-theory primitives for uncertain choices, utility, Bayesian decisions, regret, value of information, MCDA, options, and bandits. Use when choosing under uncertainty.
Decision brief
11 canonical decision-theory primitives for decisions under uncertainty. Each primitive is a formal tool with defined inputs, outputs, and failure modes. Primitives are domain-agnostic: the same expected-utility calculation that gates a product launch gates a capital investment;…
Compatibility matrix
| Platform | Status | Evidence | What to check |
|---|---|---|---|
| Codex | Not declared | No explicit evidence | Portability before use |
| Claude Code | Not declared | No explicit evidence | Portability before use |
| Cursor | Not declared | No explicit evidence | Portability before use |
| Gemini CLI | Not declared | No explicit evidence | Portability before use |
Installation
The source command is displayed only when detected. A safe inspection prompt is always available so your agent can explain every action before execution.
npx skills add https://github.com/vasilyu1983/AI-Agents-public --skill "frameworks/shared-skills/skills/foundations-decision-theory"Inspect the Agent Skill "foundations-decision-theory" from https://github.com/vasilyu1983/AI-Agents-public/blob/53f6cb73ea53a2646e3e7d4665062ad66f3683ac/frameworks/shared-skills/skills/foundations-decision-theory/SKILL.md at commit 53f6cb73ea53a2646e3e7d4665062ad66f3683ac. List every install step, command, network request, credential, file read/write, external action, and rollback step. Explain whether it fits my task. Do not install or execute anything until I approve.
Workflow
1. Identify the decision structure: risky choice, ambiguous probabilities, sequential learning, or multi-objective ranking. 2. Use the Decision Checklist to select the applicable primitive(s). 3. Open the per-primitive playbook in assets/templates/decision-theory/ for the full d…
Apply decision-theory when: - Single irreversible call under uncertainty (launch / kill / restructure) - Value-of-information question — "is the next experiment worth running?" - Real-options framing — staged investment with kill criteria - Multi-criteria choice with explicit we…
Review the “Quick Reference” section in the pinned source before continuing.
Each primitive has a full playbook (definition, when to use, inputs, outputs, failure modes, worked example, sources).
Use references/formal-theory-map.md when the task needs theorem assumptions, estimand boundaries, or a normative-vs-descriptive split.
Permission review
No configured static risk pattern was detected
This is not proof of safety. Runtime behavior, indirect dependencies, and hidden external systems are outside the static scan.
Evidence record
| Signal | Value | Evidence type | Meaning |
|---|---|---|---|
| Quality score | 93/100 | Computed | Documentation, specificity, maintenance, and trust rules |
| Repository stars | 82 | Source | Repository attention, not individual Skill quality |
| Compatibility | 0 platforms | Source | Declared in the catalog source record |
| Usage guide | automated source guide | Editorial | Generated or reviewed according to the visible evidence level |
Pinned source
11 canonical decision-theory primitives for decisions under uncertainty. Each primitive is a formal tool with defined inputs, outputs, and failure modes. Primitives are domain-agnostic: the same expected-utility calculation that gates a product launch gates a capital investment; the same EVPI formula that sizes a market research study sizes a pre-launch pilot.
Apply decision-theory when:
Skip and use simpler alternatives when:
| # | Primitive | When to Reach For It |
|---|---|---|
| 1 | Expected Utility (EU) | Ranking risky options when outcomes are commensurable |
| 2 | Bayesian Decision | Updating action after observing evidence; minimizing posterior expected loss |
| 3 | Minimax Regret | Adversarial or ambiguous probability; Savage-style robustness |
| 4 | Value of Information | Deciding whether to run an experiment, study, or pilot |
| 5 | Multi-Criteria Decision Analysis | Ranking options on incommensurable objectives |
| 6 | Risk Aversion | Adjusting EU for concave utility; certainty-equivalent pricing |
| 7 | Real Options | Valuing flexibility: defer, expand, or abandon |
| 8 | Prospect Theory | Predicting or correcting human choice under risk |
| 9 | Ellsberg and Allais Paradoxes | Diagnosing EU violations under ambiguity and certainty effects |
| 10 | Multi-Armed Bandit | Sequential exploration–exploitation under uncertainty |
| 11 | Stochastic Dominance | Distribution-level ranking without specifying a utility function |
Each primitive has a full playbook (definition, when to use, inputs, outputs, failure modes, worked example, sources).
| # | Primitive | Failure Mode It Addresses |
|---|---|---|
| 1 | Expected Utility | Choosing options by raw expected value, ignoring risk |
| 2 | Bayesian Decision | Acting on prior beliefs without updating on available evidence |
| 3 | Minimax Regret | Paralysis or overconfidence under deep uncertainty |
| 4 | Value of Information | Running experiments whose cost exceeds their decision value |
| 5 | Multi-Criteria Decision Analysis | Collapsing incommensurable objectives into a single number without disclosure |
| 6 | Risk Aversion | Ignoring the difference between expected value and certainty equivalent |
| 7 | Real Options | Treating irreversible decisions as if they were reversible |
| 8 | Prospect Theory | Prescriptive models failing to predict or explain actual human choice |
| 9 | Ellsberg and Allais Paradoxes | Applying EU where ambiguity aversion or certainty effects dominate |
| 10 | Multi-Armed Bandit | Fixed allocation ignoring the value of exploration |
| 11 | Stochastic Dominance | Comparing distributions only at their means |
| Theory Area | Use When | Applied Primitives It Grounds |
|---|---|---|
| Expected utility axioms | Need normative ranking under known probabilities | #1, #6, #11 |
| Bayesian decision theory | Need posterior expected loss, Bayes risk, or decision rules after evidence | #2, #4 |
| Robust decision criteria | Need action under ambiguity, adversarial states, or unclear probabilities | #3, #9 |
| Information economics | Need to decide whether evidence is worth buying | #4 |
| Multi-attribute utility | Need transparent tradeoffs across incommensurable goals | #5 |
| Real options theory | Need irreversibility, deferral, expansion, or abandonment value | #7 |
| Descriptive decision theory | Need to predict human deviations from EU | #8, #9 |
| Sequential learning theory | Need exploration-exploitation allocation | #10 |
Use references/formal-theory-map.md when the task needs theorem assumptions, estimand boundaries, or a normative-vs-descriptive split.
| Misuse | Why It Is Wrong | Required Correction |
|---|---|---|
| Optimizing expected value for a risk-averse decision maker | EV ignores utility curvature and downside pain | Compute expected utility and certainty equivalent |
| Treating MCDA weights as objective truth | Weights encode stakeholder preferences | Disclose weights and run sensitivity analysis |
| Reporting an MCDA ranking without a rank-reversal test | Adding or dropping an irrelevant alternative silently reorders the result; an audit of 27 published MCDM pipeline/dataset combinations found recomposition consistency (RRT3) failing in ~48% of examples and transitivity (RRT2) in ~15% | Run the Wang–Triantaphyllou RRT1–RRT3 tests alongside weight sensitivity (Cabral et al., arXiv:2508.00129) |
| Running experiments without VoI | A study can be statistically interesting but decision-worthless | Compute EVPI/EVSI before funding research |
| Applying EU under deep ambiguity | Unknown probabilities violate the input contract | Use minimax regret, maximin, or ambiguity-aware criteria; or use Wasserstein DRRO when sample data on states are available |
| Treating bandits as free optimization | Exploration has opportunity cost and fairness/product constraints | Set regret budget, guardrails, and stopping rules |
| Comparing only means | Distribution tails and dominance can reverse decisions | Check stochastic dominance and downside risk |
Check references/patterns-scenarios-traps.md before using outputs as decision authority.
EU (#1) and certainty-equivalent (#6) reasoning implicitly average over an ensemble of parallel outcomes for a single decision. Repeated or leveraged bets compound multiplicatively instead — the ensemble average and the time average (the growth rate one actor actually experiences across repeated plays) diverge whenever there is a nonzero chance of an absorbing floor (ruin, bankruptcy, delisting, project death). This is the ergodicity-economics critique (Peters, 2019, Nature Physics): a bet with strictly positive expected value can still have a negative time-average growth rate once outcomes compound — no utility-curvature adjustment fixes this; the fix is switching from an ensemble average to a time average.
Expert checks before applying EU/CE to a repeated or leveraged decision:
Sources: Peters, O. (2019). "The ergodicity problem in economics." Nature Physics 15, 1216–1221. Kelly, J. L. (1956). "A New Interpretation of Information Rate." Bell System Technical Journal 35(4).
Formal primitives are only as good as the probabilities, utilities, and weights fed into them. The most common failures are in elicitation, not in the arithmetic:
| Elicitation Trap | What Goes Wrong | Correction |
|---|---|---|
| Anchoring the first number | Whoever states a probability or weight first anchors the group; later "adjustments" under-correct | Elicit independently before group discussion (Delphi-style); aggregate afterward |
| False-precision point estimates | A single-point probability hides genuine uncertainty about the probability itself | Elicit ranges or a 10/50/90 percentile distribution; calibration-train the elicitor where the decision is high-stakes |
| Analysis paralysis | Teams keep requesting more studies or precision past the point where the information can change the action | Compute EVPI (#4) before approving further elicitation; stop and decide once EVPI is below the cost of refinement |
| Weights presented as objective | MCDA (#5) weights are framed as model output rather than negotiated stakeholder preference | Disclose weight provenance and run sensitivity analysis; treat weights as an input to be negotiated, not a discovered fact |
| Stated risk tolerance vs. revealed risk tolerance | Survey-elicited utility/risk-aversion parameters diverge from what the same stakeholder actually does under real stakes | Cross-check elicited CARA/CRRA parameters (#6) against revealed past choices (insurance, past bets) where available |
| Ambiguity flattened into a probability | An unknown probability is silently converted to 50/50 or a base rate, hiding ambiguity aversion | Run the Ellsberg/Allais diagnostic (#9) first; do not treat "unknown" as "known and uniform" |
Probability inputs increasingly come from an LLM rather than a human panel. Treat them as a calibrated-but-not-superhuman forecaster, and score them the same way you would score a person:
| Anti-Pattern | Decision Theory Diagnosis | Fix |
|---|---|---|
| Running an experiment when EVPI < experiment cost | VoI ignored; the information cannot improve the decision enough to justify the cost | Compute EVPI before approving any study or pilot (#4) |
| Choosing the highest-expected-value option for a risk-averse decision maker | Conflating EV with EU under concave utility; CE < EV for risk-averse agents | Apply utility function and compute certainty equivalent (#6) |
| Treating MCDA weights as objective | AHP/TOPSIS weights embed subjective preferences; different weight schemes reverse rankings | Disclose weights, run sensitivity analysis on weight perturbations (#5) |
| Applying EU under Ellsberg-type ambiguity | Decision maker exhibits ambiguity aversion — unknown probabilities trigger non-EU behavior | Switch to minimax regret (#3) or maximin for robustness; flag the ambiguity (#9) |
| Sunk-cost fallacy: not abandoning a losing project | Irreversibility conflated with commitment; option to abandon ignored | Price the option to abandon using real-options logic (#7) |
| Fixing traffic to each variant before observing response | Ignores exploration value; foregone learning from early-stopping | Use Thompson sampling or UCB; regret scales with suboptimal arm pulls (#10) |
| Comparing options only at their mean outcomes | Mean may be identical while variance differs materially | Check FSD or SSD before concluding indifference (#11) |
| Using EU where loss aversion and probability weighting apply | EU predicts poorly for mixed gains/losses around a reference point | Use prospect theory value function and probability weighting for descriptive accuracy (#8) |
Context: A team proposes a study, pilot, or A/B test before making a decision.
Worked example: Decision: ship feature A or B. Current best estimate: A = $200k value, B = $180k. Uncertainty: P(B actually better) = 0.3; expected regret if wrong = $40k. EVPI = 0.3 × $40k = $12k. Proposed A/B test costs $30k + 6 weeks → EVPI < test cost, skip the test; just ship A. If variance were higher — say P(B better) = 0.6 and regret = $100k — then EVPI = 0.6 × $100k = $60k, which exceeds the $30k cost, so the test pays for itself. EVSI refinement: a study that reduces variance by 60% (e.g. smaller sample, noisier measurement) captures 0.6 · EVPI. In the first scenario: 0.6 × $12k = $7.2k → still below $30k cost, skip. In the second: 0.6 × $60k = $36k > $30k → approve the cheaper, noisier study rather than the full test.
Context: A product team must rank features or bets across cost, reach, strategic value, and risk.
Context: Marketing budget, experiment slots, or engineering capacity must be allocated across options whose true performance is unknown.
Context: An AI agent or orchestration layer must decide whether to invoke an expensive large model, run a retrieval step, or route a query to one of several LLM backends — each with different quality-cost profiles.
Context: An agent holds an ambiguous instruction and must decide whether to ask a clarifying question or proceed on its best reading. Each question costs user patience; a wrong assumption costs a wasted trajectory.
assets/templates/decision-theory/ for the full definition, inputs, outputs, failure modes, and worked example.Single-agent decision under uncertainty
-> Define actions, states, outcomes, and constraints
-> Classify structure: risk, ambiguity, sequential learning, or multi-criteria
-> Select primitive and open playbook
-> Elicit probabilities, utilities, regret, or weights
+-- inputs weak -> run sensitivity or value-of-information check
+-- inputs usable -> compute recommendation
-> Report action, assumptions, uncertainty, and decision boundary
assets/templates/decision-theory/ (one file per primitive)assets/templates/decision-theory/README.mdreferences/formal-theory-map.mdreferences/patterns-scenarios-traps.mdreferences/primitives-overview.mddata/sources.jsonThis skill is a self-contained foundations primitive. Cross-link only to other foundations-* skills when a task requires joint coverage (e.g., foundations-game-theory for multi-agent settings, foundations-causal-inference for causal identification before decision framing).
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
Frequently asked questions
11 canonical decision-theory primitives for decisions under uncertainty. Each primitive is a formal tool with defined inputs, outputs, and failure modes. Primitives are domain-agnostic: the same expected-utility calculation that gates a product launch gates a capital investment;…
The source record exposes this install command: npx skills add https://github.com/vasilyu1983/AI-Agents-public --skill "frameworks/shared-skills/skills/foundations-decision-theory". Inspect the command and pinned source before running it.