feat: add AI operating economics skill (#368)

* feat: add AI operating economics skill

Add an evidence-led methodology for evaluating AI workflow value, cost, worker effects, quality guardrails, and authority expansion. Includes research references, durable decision templates, and six eval cases. AI assistance: Jasper, on behalf of Magnus Hedemark.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

* fix: resolve AI economics review findings

Align section numbering, evidence-language examples, and intervention-mode terminology identified by the exact-head review.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

---------

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

.claude-plugin/marketplace.json

@@ -77,6 +77,15 @@
       "strict": false,
       "description": "Design and operate an organization's AI governance system: define governance principles, operating models and decision rights, risk frameworks, lifecycle gates, and fairness, transparency, privacy, security, regulatory, and board-oversight controls. Use when standing up a governance program, tiering AI use-case risk, reviewing an LLM or agent system for governance and safety gaps, mapping a regulation to a compliance plan, scoring governance maturity, or preparing board reporting. For regulated life-sciences use cases, also cover GxP, ALCOA+, data integrity, electronic records, validation/assurance, and QMS interfaces. Do not use for interpreting regulations as legal advice (route to legal-strategy), data-governance mechanics (data-architect/data-engineering), or implementing application security (secure-software-engineering)."
     },
+    {
+      "name": "ai-operating-economics",
+      "source": "./",
+      "skills": [
+        "./ai-operating-economics"
+      ],
+      "strict": false,
+      "description": "Use when deciding whether an AI-enabled workflow should be adopted, scaled, constrained, redesigned, or retired, and the decision must connect business outcomes, worker or user effects, quality guardrails, full operating cost, telemetry, uncertainty, and accountable governance. Do not use for a standalone financial model, infrastructure cost calculation, agent evaluation design, runtime operations, or general AI governance; route those details to the neighboring specialist skills."
+    },
     {
       "name": "anydoc",
       "source": "./",

.codex-plugin/plugin.json

@@ -26,6 +26,7 @@
     "./agent-production-operations",
     "./agent-skills",
     "./ai-governance",
+    "./ai-operating-economics",
     "./anydoc",
     "./api-design-and-evolution",
     "./artifact-pyramids",

README.md

@@ -38,7 +38,11 @@ Reference for the Agent Skills open format itself — directory structure, front
 
 ### [ai-governance](ai-governance/SKILL.md)
 
-Design and operate an organization's AI governance system: governance principles, operating models and decision rights, risk frameworks, lifecycle gates, and fairness, transparency, privacy, security, regulatory, and board-oversight controls. Use when standing up or maturing a governance program, tiering AI use-case risk, reviewing an LLM/agent system for governance and safety gaps, mapping a regulation to a compliance plan, or preparing board reporting. Do not use for legal interpretation (route to legal-strategy), data-governance mechanics (data-architect/data-engineering), or implementing application security (secure-software-engineering).
+Design and operate an organization's AI governance system: governance principles, operating models and decision rights, risk frameworks, lifecycle gates, and fairness, transparency, privacy, security, regulatory, and board-oversight controls. Use when standing up or maturing a governance program, tiering use-case risk, reviewing an LLM or agent system for governance and safety gaps, mapping a regulation to a compliance plan, or preparing board reporting. Do not use for legal interpretation (route to legal-strategy), data-governance mechanics (data-architect/data-engineering), or implementing application security (secure-software-engineering).
+
+### [ai-operating-economics](ai-operating-economics/SKILL.md)
+
+Decide whether an AI-enabled workflow should be adopted, scaled, constrained, redesigned, or retired by connecting workflow outcomes, worker or user effects, quality guardrails, full operating cost, telemetry, uncertainty, and accountable governance. Routes detailed financial, statistical, analytics, evaluation, runtime, governance, and launch work to the owning specialist skills.
 
 ### [anydoc](anydoc/SKILL.md)
 

ai-operating-economics/README.md

@@ -0,0 +1,51 @@
+# AI Operating Economics
+
+A decision method for determining whether an AI-enabled workflow is creating value at an acceptable cost, quality, and human-impact boundary.
+
+## Why Install This Skill
+
+AI pilots often produce an attractive number: faster handling time, more tasks completed, lower apparent cost, or high adoption. That number is rarely enough to decide whether the intervention should scale. It may omit review work, infrastructure, quality loss, worker differences, customer effects, or the cost of changing the surrounding process.
+
+This skill helps an agent connect those dimensions into one accountable decision. It distinguishes measured workflow evidence from vendor claims, separates speed from value, inspects who benefits and who bears the cost, and produces a bounded recommendation: scale, constrain, redesign, hold, retire, or exception.
+
+After installing it, your agent can prepare an AI initiative evidence record, challenge weak ROI claims, design a value-realization review, and tell you exactly what evidence is missing before more authority or spend is granted.
+
+## What You Get
+
+| File | What it provides |
+|---|---|
+| `SKILL.md` | Core routing, operating principles, nine-step workflow, evidence classes, dispositions, pitfalls, and verification checklist |
+| `references/evidence-method.md` | Detailed comparison design, cost-boundary, worker-impact, uncertainty, and learning-loop method |
+| `references/source-index.md` | Primary and independent sources with claim scope, caveats, and permitted use |
+| `templates/ai-initiative-evidence-record.md` | Fillable record for one AI workflow or use case |
+| `templates/ai-economics-review.md` | Executive or lifecycle review template for one or more initiatives |
+| `evals/evals.json` | Six output-quality cases covering ROI claims, heterogeneous effects, incomplete TCO, vendor evidence, authority, and retirement |
+
+## Quick Start
+
+No setup, API keys, or runtime dependencies are required.
+
+Ask your agent:
+
+```text
+Review this AI pilot and tell me whether we should scale it. Separate measured outcomes, cost, quality countermetrics, worker effects, evidence gaps, and the authority we should grant next.
+```
+
+For a durable review, ask it to use `templates/ai-initiative-evidence-record.md` and save the completed record in your normal project documentation system.
+
+## Triggers
+
+Load this skill when you need to:
+
+- Evaluate an AI use case, pilot, agent, or automation for value realization
+- Decide whether to scale, constrain, redesign, hold, or retire an AI workflow
+- Review AI productivity, savings, adoption, or transformation claims
+- Connect AI cost attribution to workflow outcomes and quality
+- Assess worker, customer, user, or distributional effects of an AI intervention
+- Prepare an AI business case or post-launch value review
+
+## Requirements
+
+- No runtime dependencies or external services
+- A stated workflow and decision owner are strongly recommended
+- Financial, statistical, analytics, evaluation, governance, and runtime details are routed to adjacent skills

ai-operating-economics/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: ai-operating-economics
+description: >-
+  Use when deciding whether an AI-enabled workflow should be adopted, scaled,
+  constrained, redesigned, or retired, and the decision must connect business
+  outcomes, worker or user effects, quality guardrails, full operating cost,
+  telemetry, uncertainty, and accountable governance. Do not use for a standalone
+  financial model, infrastructure cost calculation, agent evaluation design,
+  runtime operations, or general AI governance; route those details to the
+  neighboring specialist skills.
+license: MIT
+compatibility: Agent-agnostic methodology; no runtime dependency.
+metadata:
+  tags: ai-economics, value-realization, ai-adoption, outcome-measurement, cost-attribution, worker-impact, evidence-led-decisions
+  source: "Synthesized from primary and independent sources listed in references/source-index.md"
+---
+
+# AI Operating Economics
+
+## Overview
+
+AI initiatives are operating interventions, not merely model purchases or ROI spreadsheets. Their value depends on what work changes, who benefits, what quality or risk changes with it, what the complete intervention costs, and whether the organization can observe and govern those changes.
+
+This skill provides the cross-domain decision spine for evaluating an AI-enabled workflow. It does not replace financial modeling, product measurement, statistical inference, agent evaluation, runtime operations, or AI governance. It makes those inputs meet in one accountable decision record.
+
+The core question is not “Did the model make people faster?” It is: “What changed in this workflow, for whom, at what full cost, with what outcome and countermetric evidence, and what authority should the organization grant next?”
+
+## When to Use
+
+Load this skill when the user needs to:
+
+- Build an evidence-backed business case for an AI use case or agentic workflow.
+- Decide whether an AI pilot should scale, remain bounded, be redesigned, or stop.
+- Review claimed AI productivity, savings, adoption, or transformation results.
+- Design an AI value-realization or post-launch outcome review.
+- Connect model and tool spend to workflow outcomes and worker or customer effects.
+- Compare AI options while accounting for measurement uncertainty and non-comparable evidence.
+- Prepare an executive, product, portfolio, or lifecycle decision about an AI-enabled intervention.
+
+## When Not to Use
+
+- **Standalone financial statements, pricing, CAC/LTV, runway, or SaaS metrics:** use [financial-modeling](../financial-modeling/SKILL.md).
+- **Token, infrastructure, quota, capacity, or SLO-cost modeling:** use [capacity-and-cost-engineering](../capacity-and-cost-engineering/SKILL.md).
+- **Metric trees, event schemas, instrumentation QA, or product dashboards:** use [product-analytics-and-measurement](../product-analytics-and-measurement/SKILL.md).
+- **Experimental design, causal inference, statistical testing, or power analysis:** use [data-scientist](../data-scientist/SKILL.md).
+- **Agent datasets, graders, traces, regression analysis, or telemetry implementation:** use [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md).
+- **Production rollout, runtime budgets, authority, fallback, escalation, or disablement:** use [agent-production-operations](../agent-production-operations/SKILL.md).
+- **Organization-wide AI risk, policy, compliance, or governance operating models:** use [ai-governance](../ai-governance/SKILL.md).
+- **A launch-readiness packet or production go/no-go decision:** use [production-readiness](../production-readiness/SKILL.md).
+- **General product governance cadence without an AI-specific value question:** use [product-operations-and-governance](../product-operations-and-governance/SKILL.md).
+
+## Non-Negotiable Reasoning Rules
+
+1. **Workflow evidence beats model evidence.** A benchmark, demo, or vendor claim does not establish value in the target workflow.
+2. **Speed is not value.** Time saved can be spent on lower-value work, offset by review and exception handling, or enable higher-value work. Measure the business or user outcome directly.
+3. **Averages are not enough.** Inspect worker, user, task, geography, tenure, risk, and quality slices. An aggregate gain can hide a subgroup loss.
+4. **Every benefit metric needs a countermetric.** Pair throughput or cost with quality, safety, customer, worker, privacy, or reliability measures appropriate to the workflow.
+5. **Token cost is not total cost.** Include model calls, tools, retrieval, storage, networking, observability, engineering, human review, change management, governance, and unused committed capacity when material.
+6. **Evidence classes must stay separate.** Label observed results, causal estimates, inferences, vendor-reported findings, stakeholder assertions, and normative requirements distinctly.
+7. **Missing evidence is a decision input.** Do not turn an unknown into a favorable assumption. Record the gap, owner, consequence, and next evidence needed.
+8. **Authority follows evidence.** A positive pilot does not justify unrestricted autonomy. Scale capability and authority in bounded slices with explicit reversal conditions.
+9. **Do not manufacture precision.** Use ranges, scenarios, sensitivity, and confidence where inputs are uncertain. Do not rank non-comparable studies or vendors.
+10. **The decision is reversible only if the artifact says how.** Record the stop trigger, rollback or containment path, decision owner, and review date.
+
+## Core Workflow
+
+Use this sequence for an AI initiative review. Load the detailed method and the evidence-record template when the task requires a durable artifact.
+
+### 1. Define the intervention and decision
+
+Name the workflow, population, task boundary, intervention mode, baseline, decision sought, and decision owner. State whether the AI assists, recommends, routes, executes, or replaces/removes work. Define what remains human-controlled.
+
+Do not begin with the model name or a claimed percentage. Begin with the work that changes and the decision the evidence must support.
+
+### 2. State the value hypothesis
+
+Write a falsifiable hypothesis:
+
+> For [population] doing [workflow], [intervention] will change [outcome] by [direction/range] without exceeding [countermetric boundary], at [full operating cost boundary], compared with [baseline], over [period].
+
+If the proposed outcome is only “productivity,” decompose it into the actual customer, employee, operational, financial, or mission outcome. If the outcome cannot be observed or credibly proxied, mark the initiative measurement-incomplete rather than inventing a proxy.
+
+### 3. Build the outcome and countermetric map
+
+Define:
+
+- Primary outcome: the result the initiative exists to improve.
+- Leading indicators: early evidence that the mechanism is operating.
+- Countermetrics: quality, safety, customer, worker, privacy, reliability, or equity measures that could worsen.
+- Adoption and substitution measures: who uses the system, what work changes, and what work is displaced or added.
+- Guardrail thresholds: contextual limits with an owner and response.
+
+Route metric definitions and instrumentation plans to product analytics. Route statistical or causal design to data science. This skill owns the connection between the evidence and the decision, not the detailed statistical method.
+
+### 4. Establish the full economic boundary
+
+Record both:
+
+- **Marginal economics:** what changes when one more task, user, or workflow unit is served.
+- **Fully loaded economics:** the costs required to make the intervention available and govern it.
+
+At minimum consider inference, tool use, retrieval, storage, data transfer, observability, engineering, evaluation, human review, training, support, change management, governance, security, and committed capacity. Separate fixed, variable, step-function, and avoided costs. Define the denominator precisely: task, resolved case, completed workflow, active user, customer outcome, or another meaningful unit.
+
+Route the detailed model to capacity-and-cost-engineering or financial-modeling. Never divide total spend by an undifferentiated request count when requests have materially different resource or outcome profiles.
+
+### 5. Design the evidence comparison
+
+Choose the strongest feasible comparison before interpreting results:
+
+- Randomized or staggered rollout when feasible.
+- Matched or difference-in-differences comparison when appropriate.
+- Within-workflow baseline with explicit pre-period and seasonality limits.
+- Controlled pilot with a documented task and population boundary.
+- Descriptive before/after evidence only when stronger designs are infeasible, labeled accordingly.
+
+Record selection effects, learning effects, concurrent initiatives, task-mix changes, worker self-selection, quality measurement gaps, and changes in pay or incentives. If the comparison cannot support the requested claim, narrow the claim rather than upgrading the method rhetorically.
+
+### 6. Segment before aggregating
+
+Report the overall result and inspect slices that could change the decision:
+
+- Worker experience, skill, role, and training status.
+- Task complexity, risk, volume, and exception rate.
+- Customer or user segment.
+- Geography, language, accessibility, and relevant demographic groups when lawful and appropriate.
+- Human-review burden and escalation path.
+- Quality, safety, and error severity.
+
+Treat heterogeneous effects as a finding, not noise to average away. A tool that helps novices while harming expert quality may need differentiated assistance modes, not universal rollout.
+
+### 7. Classify the evidence
+
+For every material claim, label it:
+
+| Class | Meaning | Permitted use |
+|---|---|---|
+| Observed | Directly measured in the target workflow with a stated method | Describe what happened within the stated scope |
+| Causal estimate | Supported by a credible comparison or experiment | Attribute an effect only within the design's limits |
+| Inferred | Reasoned from observed evidence and explicit assumptions | Guide a bounded hypothesis or scenario |
+| Vendor-reported | Provider survey, case study, or product documentation | Establish reported adoption or available capability, not realized ROI |
+| Asserted | Stakeholder or proposal claim not yet verified | Track as an assumption and evidence gap |
+| Normative | Standard or framework recommendation | Define a control expectation, not an outcome claim |
+
+Keep the source, access date, scope, version, caveat, and permitted interpretation with each claim. Load `references/source-index.md` for the research basis and evidence boundaries.
+
+### 8. Produce a bounded decision
+
+Choose exactly one primary disposition:
+
+- **Scale:** evidence supports expansion within a named scope and authority boundary.
+- **Constrain:** value is plausible, but cost, quality, risk, or distributional effects require limits.
+- **Redesign:** the mechanism or workflow needs modification before another test.
+- **Hold:** evidence is insufficient for the requested decision; specify the missing evidence.
+- **Retire:** observed value is absent or countermetrics exceed acceptable bounds, with a transition path.
+- **Exception:** proceed despite a named gap only with an accountable human approver, expiry or revisit trigger, and containment plan.
+
+A decision is incomplete without an owner, review date or trigger, evidence gaps, and reversal path. Route launch or runtime consequences to the appropriate specialist skill.
+
+### 9. Close the learning loop
+
+At the review date, compare expected versus observed outcomes, cost, quality, worker or user effects, adoption, and incidents. Preserve the updated evidence record and state whether the prior hypothesis was supported, weakened, refuted, or still unresolved. Feed verified incidents and near misses into evaluation and governance work rather than treating them as anecdotal follow-up.
+
+## Load-on-Demand References
+
+| Need | Load |
+|---|---|
+| Apply the full research and decision method, including comparison design and uncertainty | [references/evidence-method.md](references/evidence-method.md) |
+| Review the sources and their permitted interpretations | [references/source-index.md](references/source-index.md) |
+| Fill a durable initiative record before a review | [templates/ai-initiative-evidence-record.md](templates/ai-initiative-evidence-record.md) |
+| Prepare an executive or lifecycle review from one or more initiative records | [templates/ai-economics-review.md](templates/ai-economics-review.md) |
+
+## Common Pitfalls
+
+- Treating an AI benchmark, speed increase, or demo as evidence of business value.
+- Treating a vendor survey as an audited financial result or causal estimate.
+- Reporting one average while omitting worker, task, quality, or customer slices.
+- Calling token spend “AI cost” while omitting review, tooling, retrieval, infrastructure, or change costs.
+- Choosing a denominator that makes the economics look favorable, such as all requests instead of completed or resolved workflows.
+- Treating a missing baseline as zero or assuming adoption means benefit.
+- Using a normative framework as proof that an intervention is safe or effective.
+- Granting broader authority because a pilot had a positive mean result.
+- Reusing a prior decision after the workflow, model, population, cost boundary, or evidence source changed.
+- Writing a sophisticated recommendation without preserving the source-level evidence that supports it.
+
+## Verification Checklist
+
+Before delivering an AI operating economics decision, verify:
+
+- [ ] The workflow, intervention, population, baseline, decision owner, and human-control boundary are explicit.
+- [ ] The value hypothesis is falsifiable and tied to an observable outcome.
+- [ ] At least one countermetric is defined for each benefit claim.
+- [ ] Fixed, variable, step-function, and fully loaded costs are separated where material.
+- [ ] The denominator represents meaningful work or value, not merely requests or tokens.
+- [ ] The comparison design and its limitations are stated.
+- [ ] Relevant worker, user, task, quality, and risk slices are inspected or explicitly unavailable.
+- [ ] Claims are labeled by evidence class and traced to sources.
+- [ ] Missing evidence is visible with an owner and next step.
+- [ ] The disposition, authority boundary, reversal path, and review trigger are recorded.
+- [ ] Detailed statistical, financial, instrumentation, governance, runtime, and launch checks were routed to their owning skills.
+
+## Exit Criteria
+
+Stop when the requested decision is supported by a durable evidence record, or when a bounded hold/escalation is the honest result. Do not continue refining prose to conceal missing evidence.

ai-operating-economics/evals/evals.json

@@ -0,0 +1,85 @@
+{
+  "schema_version": 1,
+  "skill_name": "ai-operating-economics",
+  "evals": [
+    {
+      "id": "aggregate-speed-claim",
+      "prompt": "Our support pilot reduced average handle time by 18% and the vendor says this proves a 20% productivity gain. Customer satisfaction was measured for only 10% of chats, and we have no baseline comparison. Should we roll it out to every team?",
+      "expected_output": "A bounded recommendation that rejects the conclusion that lower handle time proves productivity or supports universal rollout. It identifies the missing baseline, incomplete quality measurement, and the need to measure a meaningful outcome such as resolved cases or customer outcomes alongside quality countermetrics. It proposes a scoped comparison and a constrained next step rather than a universal rollout.",
+      "assertions": [
+        "The response explicitly says reduced handle time alone does not establish business value or productivity",
+        "The response identifies both the missing baseline and the 10% customer-satisfaction coverage as material evidence gaps",
+        "The response distinguishes the vendor claim from observed or causal evidence",
+        "The response proposes a meaningful primary outcome and at least one quality countermetric",
+        "The response does not automatically convert time saved into salary savings and identifies the benefit-realization mechanism that would be needed",
+        "The recommendation is bounded to a scoped pilot, hold, or constrained rollout rather than universal rollout"
+      ],
+      "case_set": "release"
+    },
+    {
+      "id": "heterogeneous-effects",
+      "prompt": "An AI assistant increased completed cases per hour by 14% overall. New employees improved by 34%, experienced employees showed no improvement, and quality audits suggest a small decline among the highest performers. What should the company do next?",
+      "expected_output": "A segmented decision that treats heterogeneous effects as central evidence. It does not recommend universal scale from the mean. It proposes differentiated deployment, further quality investigation, and separate authority or workflow treatment for affected groups, with an owner and reversal trigger.",
+      "assertions": [
+        "The response treats worker heterogeneity as a decision-changing finding rather than noise",
+        "The response does not recommend unconditional universal rollout based on the 14% average",
+        "The response addresses the possible quality decline among highest performers",
+        "The response proposes a differentiated or bounded next intervention",
+        "The response includes a review or reversal trigger tied to quality and subgroup outcomes"
+      ],
+      "case_set": "release"
+    },
+    {
+      "id": "incomplete-tco",
+      "prompt": "Our agent costs $0.004 per request in model tokens. Finance wants to approve the project because that is cheaper than a $0.12 human-handled request. The agent also uses retrieval, three APIs, a vector database, observability, human exception review, and a dedicated GPU that is idle 40% of the time. Prepare the economic comparison.",
+      "expected_output": "A corrected comparison that rejects token-only cost as total cost. It defines a meaningful denominator, separates marginal from fully loaded cost, includes retrieval, tools, storage, observability, human review, and committed or idle capacity, and identifies the evidence needed to calculate each component. It does not claim savings until the workflow outcomes and quality boundary are established.",
+      "assertions": [
+        "The response explicitly rejects model-token cost as the complete economic comparison",
+        "The response separates marginal cost from fully loaded cost",
+        "The response includes retrieval, APIs/tools, vector storage, observability, human exception review, and idle dedicated capacity",
+        "The response defines or requests a meaningful denominator beyond raw requests",
+        "The response states that cost savings cannot be claimed without workflow outcome and quality evidence"
+      ],
+      "case_set": "dev"
+    },
+    {
+      "id": "vendor-survey-evidence",
+      "prompt": "A consulting firm's survey says 66% of organizations report AI productivity gains and 40% report cost reductions. The board wants a memo saying our AI program will produce the same results. How should the evidence be used?",
+      "expected_output": "A calibrated memo that labels the survey as vendor-reported self-report evidence, uses it only as context or hypothesis-generation, and refuses to project the percentages onto the organization without a local baseline, workflow evidence, cost boundary, and countermetrics.",
+      "assertions": [
+        "The response labels the survey as vendor-reported and self-reported rather than audited causal evidence",
+        "The response refuses to treat the survey percentages as a forecast for this organization",
+        "The response identifies a local baseline and workflow-specific evidence as needed",
+        "The response requests quality or other countermetrics alongside productivity or cost claims",
+        "The response offers a calibrated alternative for board language"
+      ],
+      "case_set": "regression"
+    },
+    {
+      "id": "authority-after-pilot",
+      "prompt": "Our read-only internal agent passed its pilot evaluation with a strong average score. The product team now wants to let it update customer records automatically. What does the economics review need to decide?",
+      "expected_output": "A decision that separates value evidence from authority expansion. It requires a new intervention and risk boundary, side-effect evaluation, authorization and rollback controls, cost and quality monitoring, staged expansion, and a named human owner. A positive read-only pilot is not treated as evidence for write authority.",
+      "assertions": [
+        "The response says a positive read-only pilot does not establish safety or readiness for customer-record writes",
+        "The response identifies authority expansion as a new intervention requiring separate evidence",
+        "The response requires authorization, rollback or containment, and human escalation controls",
+        "The response proposes staged or bounded authority rather than an immediate unrestricted change",
+        "The response names cost, quality, and side-effect monitoring as part of the decision"
+      ],
+      "case_set": "release"
+    },
+    {
+      "id": "retirement-decision",
+      "prompt": "After six months, an AI workflow has high adoption but no measurable improvement in the intended customer outcome. Reviewers also spend significant time correcting its outputs, and the cost ledger is incomplete. The sponsor says adoption proves the system should continue. Produce the lifecycle recommendation.",
+      "expected_output": "A recommendation that does not equate adoption with value. It makes the incomplete cost ledger and correction burden visible, assesses the intended outcome and quality countermetric, and recommends hold, redesign, or retirement with a bounded evidence plan and a transition or containment path.",
+      "assertions": [
+        "The response explicitly distinguishes adoption from realized value",
+        "The response identifies correction burden and incomplete cost accounting as material",
+        "The response centers the intended customer outcome rather than usage volume",
+        "The response recommends a bounded hold, redesign, or retirement path rather than indefinite continuation",
+        "The response includes a named owner, review trigger, and transition or containment consideration"
+      ],
+      "case_set": "release"
+    }
+  ]
+}

ai-operating-economics/references/evidence-method.md

@@ -0,0 +1,212 @@
+# Evidence Method for AI Operating Economics
+
+This reference turns the core skill into a repeatable investigation and decision method. Use it when the user needs more than a short recommendation or when a claim is consequential enough to preserve.
+
+## 1. Scope the decision before gathering numbers
+
+Write a one-sentence decision question:
+
+> Should [accountable owner] [scale, constrain, redesign, hold, retire, or approve an exception for] [AI intervention] in [workflow/population] by [date or trigger], based on [required outcome and guardrails]?
+
+Record the intervention mode:
+
+- Assist: provides information or drafts while a person decides.
+- Recommend: proposes a ranked or selected action.
+- Route: classifies or directs work.
+- Execute: takes an external action.
+- Replace or remove: changes staffing, process, or service capacity.
+
+The mode determines what evidence and authority are appropriate. A positive assist result does not automatically justify execution authority.
+
+## 1a. Separate the business case from benefit realization
+
+A forecasted benefit is not a realized benefit. Track four states separately:
+
+1. **Expected benefit:** the hypothesis or business-case estimate.
+2. **Enabled capacity:** time, throughput, or capability the intervention appears to make available.
+3. **Operational benefit:** a verified change in the target workflow, such as more resolved cases, shorter cycle time without quality loss, or fewer avoidable escalations.
+4. **Realized economic or mission benefit:** the operational change is converted into an attributable financial, service, capacity, or mission result under the organization's actual decision and accounting rules.
+
+Record the owner, baseline, realization mechanism, timing, dependencies, and disbenefits for each expected benefit. Do not call time saved “savings” until the organization has a credible mechanism for converting it into reduced spend, additional output, avoided cost, improved service, or another explicitly valued result. If the benefit is capacity released for higher-value work, measure whether that work actually occurred.
+
+Benefits-realization planning can borrow from public-sector benefits-management guidance, but the local owner and accounting treatment remain authoritative. Load the source index when a board or investment claim depends on the distinction.
+
+## 2. Gather evidence by claim, not by headline
+
+Build a claim table before writing the conclusion:
+
+| Claim | Evidence class | Source and scope | What it supports | What it does not support | Open challenge |
+|---|---|---|---|---|---|
+| [claim] | observed / causal / inferred / vendor-reported / asserted / normative | [citation, date, version] | [permitted interpretation] | [boundary] | [test or missing evidence] |
+
+Use the strongest source appropriate to the claim:
+
+- Workflow outcomes: controlled studies, internal experiments, or verified operational data.
+- Cost: billing records, usage telemetry, allocation rules, and explicit assumptions.
+- Quality and safety: outcome audits, incident records, domain review, and representative samples.
+- Worker or user impact: segmented operational data plus worker/user research where relevant.
+- Controls: official standards, provider documentation, and observed enforcement behavior.
+
+A research summary is not a substitute for source-level claims. Preserve rejected, inaccessible, redundant, or out-of-scope sources in the research log or evidence record so omission is distinguishable from oversight.
+
+## 3. Build an outcome model
+
+Separate the mechanism from the outcome:
+
+| Layer | Question | Example |
+|---|---|---|
+| Intervention | What changed? | Agent receives suggested responses |
+| Behavior | What did people or systems do differently? | More chats handled; recommendations accepted selectively |
+| Immediate outcome | What changed in the workflow? | Resolved cases per hour |
+| Quality outcome | Did the result remain correct and acceptable? | Resolution rate, customer sentiment, rework |
+| Business or mission outcome | Did the organization get the intended value? | Cost per resolved case, retention, revenue, service access |
+| Distributional outcome | Who gained, lost, or carried new burden? | Novices improve; experts see no gain; review work shifts |
+
+Do not jump from intervention to business outcome without observing the intermediate mechanism and its failure modes.
+
+## 4. Design the comparison
+
+Choose the strongest feasible design and name the downgrade if it is weaker:
+
+1. Randomized or staggered assignment.
+2. Matched comparison or difference-in-differences with a defensible control and pre-period.
+3. Controlled pilot with explicit inclusion, exclusion, baseline, and observation window.
+4. Before/after descriptive comparison with seasonality, selection, and concurrent-change caveats.
+5. Qualitative or vendor evidence used only for hypothesis formation.
+
+Before interpreting a result, ask:
+
+- Did people self-select into treatment or into using the tool?
+- Did task mix, volume, staffing, incentives, or pay change?
+- Did the intervention change which tasks were attempted?
+- Did quality measurement cover the treated population equally?
+- Did learning, novelty, or temporary support affect the result?
+- Were concurrent tools, process changes, or policy changes present?
+- Is the comparison at the same workflow boundary as the decision?
+
+If these questions cannot be answered, narrow the causal language and classify the result as descriptive or inferred.
+
+## 5. Model the economic boundary
+
+Use three cost layers, then show marginal and fully loaded views within the economic layer:
+
+1. **Billing truth:** provider or infrastructure charges as recorded in source billing data.
+2. **Allocated cost:** shared charges assigned to a product, team, tenant, workflow, or business unit under documented allocation rules.
+3. **Economic cost:** allocated cost plus material human, engineering, governance, risk, idle-capacity, transition, and opportunity costs needed to operate the intervention.
+
+A common billing schema can improve reconciliation and allocation, but it does not decide the right allocation policy or establish business value.
+
+### Marginal view
+
+What changes when one more meaningful unit of work is served?
+
+- Input and output tokens
+- Model and routing charges
+- Data acquisition, preparation, licensing, and retention
+- Tool and API calls
+- Retrieval and data transfer
+- Human review, correction, escalation, and rework
+- Incremental compute or capacity
+
+### Fully loaded view
+
+What must exist for the intervention to operate responsibly?
+
+- Engineering and integration
+- Evaluation and test data
+- Red-teaming and monitoring
+- Observability and retention
+- Security, privacy, and governance
+- Training, change management, and support
+- Incident response and recovery
+- Committed or idle capacity
+- Model/provider migration, retraining, deprecation, and exit costs
+
+Classify each cost as fixed, variable, step-function, avoided, transferred, or uncertain. State the allocation method for shared resources. Keep token attribution separate from realized value: tokens are a computation unit, not a value unit.
+
+The denominator must represent meaningful work. Possible denominators include completed workflow, resolved case, accepted decision, active user-month, or customer outcome. Use separate denominators for materially different task classes rather than hiding them in an average.
+
+## 6. Inspect worker, user, and task heterogeneity
+
+At minimum, slice by the variables that could reverse the decision:
+
+- Experience, skill, role, and training status
+- Task complexity, risk, and exception rate
+- Customer or user segment
+- Language, geography, accessibility, or demographic group where appropriate and lawful
+- Human-review burden and escalation frequency
+- Quality, error severity, and rework
+- Adoption intensity and non-user comparison
+
+A heterogeneous result may require differentiated deployment: assistance for novices, review support for experts, a higher-quality model for high-risk tasks, or no deployment in a harmed segment. Do not “solve” heterogeneity by reporting only the mean.
+
+Worker-impact evidence should include more than productivity. Consider autonomy, workload, learning, skill development, job quality, schedule, stress, discretion, and who absorbs monitoring or correction work. Route formal labor, legal, or collective-bargaining questions to qualified specialists.
+
+## 7. Separate evidence from decision language
+
+Use calibrated verbs:
+
+- **Observed:** “The treated group resolved more cases per hour in this deployment.”
+- **Causal:** “The staggered comparison estimates an increase within this population and period.”
+- **Inferred:** “The pattern is consistent with knowledge transfer, but does not establish it.”
+- **Vendor-reported:** “The provider reports that customers experienced…”
+- **Asserted:** “The sponsor claims…” or “The proposal assumes…”; do not present it as observed.
+- **Normative:** “The framework recommends monitoring and assigned responsibility.”
+- **Unknown:** “The available evidence does not establish…”
+
+Never use “proves,” “guarantees,” “will save,” or “safe” unless the evidence and scope truly support that strength.
+
+## 7a. Require a governance evidence packet for authority expansion
+
+Before moving from a bounded pilot to a materially broader population, higher-risk task, or side-effect authority, require a compact governance packet:
+
+- Accountable owner, intended use, risk tier, and affected population
+- System, model, prompt/policy, tool, provider, and version inventory
+- Acceptable-use, refusal, escalation, and human-oversight rules
+- Pre-deployment evaluation results and the release threshold used
+- Third-party/provider assessment and relevant contractual evidence
+- Incident, override, and near-miss record with after-action ownership
+- Change and revalidation trigger for model, prompt, tool, data, or workflow changes
+- Retention, dependency, leakage, user-impact, and decommissioning plan
+
+These are governance inputs, not proof that the system is safe or valuable. Include the cost of producing and operating these controls in the economic boundary. Route detailed risk, privacy, security, and runtime control work to their owning skills.
+
+## 8. Apply a decision rule without pretending to score everything
+
+Use a structured disposition rather than a universal numeric score:
+
+| Disposition | Minimum basis | Required next control |
+|---|---|---|
+| Scale | Outcome improvement, countermetrics within bounds, cost boundary understood, no disqualifying slice | Define next population and authority slice |
+| Constrain | Plausible value with unresolved cost, quality, distributional, or authority risk | Set quota, population, task, or human-review boundary |
+| Redesign | Mechanism or workflow creates avoidable failure or burden | Change workflow/model/control and rerun comparison |
+| Hold | Required evidence is missing or conflicting | Name evidence owner, method, and review trigger |
+| Retire | Value absent or countermetrics exceed bounds after review | Protect users/workers, migrate, and record learning |
+| Exception | Material gap accepted temporarily | Named human approver, expiry, containment, and revisit |
+
+A positive average cannot override a hard safety, privacy, authorization, or material quality failure. Conversely, a single weak metric should not automatically kill an intervention if the decision record explains the tradeoff and names the accountable owner.
+
+## 9. Close the loop
+
+At the review trigger, compare:
+
+- Expected versus observed outcome
+- Expected versus observed cost
+- Countermetrics and subgroup effects
+- Adoption, substitution, and new human work
+- Incidents, near misses, overrides, and escalations
+- Model, prompt, tool, policy, or population changes
+
+Classify the hypothesis as supported, weakened, refuted, or unresolved. Preserve the result and link it to the next decision. A value-realization process that never changes authority, scope, or investment is measurement theater.
+
+## Research thin spots to keep visible
+
+The foundational evidence is strongest for workflow-level productivity, measurement caution, cost/usage controls, telemetry, and lifecycle governance. It is thinner for:
+
+- Realized financial returns after implementation and change-management cost
+- Long-term worker learning, job quality, and distributional effects
+- Agentic workflows with multiple tools and autonomous side effects
+- Comparable cross-vendor or cross-model economic benchmarks
+- Enterprise counterfactuals where adoption is voluntary and task mix changes
+
+Treat these as active evidence gaps. Do not fill them with vendor case studies or invented benchmarks.

ai-operating-economics/references/source-index.md

@@ -0,0 +1,61 @@
+# Source Index and Evidence Boundaries
+
+This index records the research basis for the skill. Access dates and versions should be refreshed when a decision depends on a time-sensitive provider capability. These sources inform method and guardrails; they do not establish universal ROI.
+
+## Workflow outcome and measurement
+
+| Source | Evidence type | Supports | Does not support |
+|---|---|---|---|
+| [Brynjolfsson, Li, and Raymond, Generative AI at Work](https://www.nber.org/papers/w31161) | Independent working paper, revised 2023 | In one customer-support deployment, AI assistance increased resolved issues per hour by about 14% on average, with much larger gains for novice/lower-skilled workers and minimal gains for experienced/high-skilled workers; the paper also examines quality, sentiment, retention, adherence, and learning | General enterprise ROI, current agentic-system performance, or universal productivity claims |
+| [NBER digest summary](https://www.nber.org/digest/20236/measuring-productivity-impact-generative-ai) | Independent study summary | Plain-language description of the measured deployment and heterogeneous effects | A substitute for the working paper when methodological detail matters |
+| [METR, Uplift Update](https://metr.org/blog/2026-02-24-uplift-update/) | Independent measurement research | Selection effects, task-selection bias, concurrent-agent accounting, and why an attractive developer-speed estimate may not support a strong causal claim | A general estimate of enterprise AI productivity |
+| [METR, AI Usage Survey](https://metr.org/blog/2026-05-11-ai-usage-survey/) | Independent survey research | The distinction between speed and value, plus caveats on self-reported uplift and counterfactual estimation | Audited financial ROI or causal productivity evidence |
+| [Noy and Zhang, Experimental Evidence on the Productivity Effects of Generative Artificial Intelligence](https://economics.mit.edu/sites/default/files/inline-files/Noy_Zhang_1.pdf) | Randomized experiment manuscript | Short writing-task effects on completion time, blinded quality, performer heterogeneity, task composition, and the limits of inferring durable workplace value | Firm-level ROI, long-term skill development, or generalization to organization-specific work |
+| [OECD Employment Outlook 2023: AI, job quality and inclusiveness](https://www.oecd.org/en/publications/oecd-employment-outlook-2023_08785bba-en/full-report/artificial-intelligence-job-quality-and-inclusiveness_a713d0ad.html) | Independent policy research | Worker, management, working-condition, skill, productivity, wage, employment, and transition dimensions that should accompany a narrow productivity measure | A universal prediction of AI's labor-market impact or a substitute for local worker evidence |
+| [OECD case studies of AI implementation](https://www.oecd.org/content/dam/oecd/en/publications/reports/2023/03/the-impact-of-ai-on-the-workplace-evidence-from-oecd-case-studies-of-ai-implementation_b4c2c6ee/2247ce58-en.pdf) | Independent case research | Heterogeneity across worker profiles, sectors, countries, task composition, skill requirements, and job quality | A causal benchmark for a specific organization |
+
+## Cost and usage
+
+| Source | Evidence type | Supports | Does not support |
+|---|---|---|---|
+| [FinOps for AI overview](https://www.finops.org/wg/finops-for-ai-overview/) | Primary foundation guidance | Extending FinOps practices to volatile model pricing, token meters, GPU scarcity, allocation, quotas, tagging, and outcome alignment | Proof that any organization has realized savings |
+| [How to Build a Generative AI Cost and Usage Tracker](https://www.finops.org/wg/how-to-build-a-generative-ai-cost-and-usage-tracker/) | Primary foundation guidance | Token attribution levels, centralized or common interfaces, shared-throughput allocation, and the need to account for more than inference | A universal architecture or exact savings formula |
+| [GenAI FinOps: How Token Pricing Really Works](https://www.finops.org/wg/genai-finops-how-token-pricing-really-works/) | Primary foundation guidance | The warning that advertised token prices do not describe complete application TCO | A measured cross-provider cost comparison |
+| [Token Economics: The Atomic Unit of AI Value](https://www.finops.org/insights/token-economics-the-atomic-unit-of-ai-value/) | Primary foundation insight | Tokens are computation units and require contextual interpretation | Tokens as a direct measure of business value |
+
+## Benefits realization and cost estimation
+
+| Source | Evidence type | Supports | Does not support |
+|---|---|---|---|
+| [UK Digital and Data Benefits Framework](https://www.gov.uk/government/publications/digital-and-data-benefits-framework/digital-and-data-benefits-framework) | Government guidance | Distinguishing benefits, disbenefits, measures, owners, baselines, dependencies, and realization tracking in a digital business case | A universal accounting treatment or proof that a forecast benefit will be realized |
+| [UK Magenta Book evaluation guidance](https://www.gov.uk/government/publications/the-magenta-book/magenta-book-central-government-guidance-on-evaluation-html) | Government evaluation guidance | Evaluation planning, theory of change, counterfactual reasoning, monitoring, and proportionate evidence design | A replacement for domain-specific statistical or financial expertise |
+| [FinOps Open Cost and Usage Specification (FOCUS)](https://focus.finops.org/focus-specification/) | Primary specification | A common structure for normalizing billing data and supporting reconciliation, allocation, chargeback, budgeting, and forecasting | Complete TCO, causal ROI, labor cost, or the correct local allocation policy |
+| [GAO Cost Estimating and Assessment Guide](https://www.gao.gov/products/gao-20-195g) | Government cost-estimation guidance | Lifecycle cost categories, documented assumptions, uncertainty, sensitivity, independent review, and updating estimates as evidence changes | An AI-specific cost model or a guarantee of estimate accuracy |
+
+## Governance and worker impact
+
+| Source | Evidence type | Supports | Does not support |
+|---|---|---|---|
+| [NIST AI RMF: Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf) | Primary voluntary framework | Generative-AI-specific risk considerations, testing and evaluation, monitoring, incident response, human oversight, and lifecycle controls | Certification, compliance, safety proof, or realized value |
+| [ISO/IEC 42001](https://www.iso.org/standard/42001) | International standard description | The AI management-system idea: objectives, responsibilities, performance evaluation, corrective action, and continual improvement | Certification or conformance without an authorized audit and the applicable standard |
+| [ILO, Generative AI and Jobs](https://webapps.ilo.org/static/english/intserv/working-papers/wp096/index.html) | Independent policy research | Job quantity and quality, autonomy, work organization, and worker voice as dimensions beyond productivity | A prediction of the impact on a particular employer or occupation |
+
+## Telemetry and controls
+
+| Source | Evidence type | Supports | Does not support |
+|---|---|---|---|
+| [OpenTelemetry GenAI observability](https://opentelemetry.io/blog/2026/genai-observability/) | Primary technical guidance | Agent, model-call, tool-execution, model/version, duration, and token telemetry; prompt and tool content should not be captured by default when sensitive | Complete production observability or a guarantee of privacy |
+| [OpenTelemetry GenAI attributes](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/) | Primary technical specification | Portable provider, model, operation, token, and agent attributes, with version/movement caveats | Stable interoperability across every implementation without version pinning |
+| [NIST AI RMF Core](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/) | Primary voluntary framework | Govern, map, measure, and manage lifecycle structure; inventory, roles, monitoring, incident response, recovery, and deactivation expectations | Certification, safety proof, or legal compliance |
+| [NIST Generative AI Profile](https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence) | Primary voluntary framework | Generative-AI-specific risk-management considerations to supplement AI RMF 1.0 | A complete implementation design or outcome guarantee |
+| [AWS Bedrock prompt routing](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-routing.html) | Vendor documentation | An example of provider-side quality/cost routing and its documented limitations | Independent savings or quality superiority |
+| [Microsoft Foundry cost management](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-models/how-to/manage-costs) | Vendor documentation | An example of estimation, representative test traffic, cost grouping, budgets, alerts, and dependent-resource TCO | Hard spend stops, universal controls, or independent ROI |
+
+## Research-use rules
+
+- Preserve the source URL, access date, evidence type, scope, and caveat with every retained claim.
+- Treat working papers as research evidence, not peer-reviewed consensus unless the source says otherwise.
+- Treat vendor documentation as capability evidence only.
+- Treat vendor surveys and case studies as reported claims, not causal outcomes.
+- Do not copy copyrighted source text into public skill content; paraphrase and link.
+- Re-verify provider capabilities and moving OpenTelemetry conventions before using them as implementation requirements.

ai-operating-economics/templates/ai-economics-review.md

@@ -0,0 +1,61 @@
+# AI Economics Review
+
+Use this template for an executive, portfolio, experiment, launch, or lifecycle review that consumes one or more AI initiative evidence records.
+
+## Review header
+
+- Review purpose:
+- Review date:
+- Operating mode: lightweight / high-assurance
+- Accountable decision-maker:
+- Records reviewed:
+- Decision deadline or trigger:
+
+## Executive decision
+
+- Disposition: scale / constrain / redesign / hold / retire / exception
+- Decision in one sentence:
+- Approved population and workflow:
+- Approved authority:
+- Budget or cost boundary:
+- Review trigger:
+
+## Evidence summary
+
+| Dimension | What was observed | Confidence/class | Material caveat | Owner |
+|---|---|---|---|---|
+| Workflow outcome | | | | |
+| Quality and safety | | | | |
+| Worker/user/customer effect | | | | |
+| Adoption and substitution | | | | |
+| Marginal economics | | | | |
+| Fully loaded economics | | | | |
+| Reliability and operations | | | | |
+| Governance and authority | | | | |
+
+## Slices that change the decision
+
+| Slice | Result | Why it matters | Required response |
+|---|---|---|---|
+| | | | |
+
+## Evidence gaps and exceptions
+
+| Gap or exception | Consequence if wrong | Owner | Control or containment | Revisit date/trigger |
+|---|---|---|---|---|
+| | | | | |
+
+## Options and trade-offs
+
+| Option | Value evidence | Cost | Quality/worker/user effects | Authority and reversibility | Recommendation |
+|---|---|---|---|---|---|
+| | | | | | |
+
+## Decision record
+
+- Why this disposition is justified:
+- What would falsify or reverse it:
+- What will not be claimed:
+- Next action:
+- Named owner:
+- Verification evidence required before the next authority or investment step:

ai-operating-economics/templates/ai-initiative-evidence-record.md

@@ -0,0 +1,131 @@
+# AI Initiative Evidence Record
+
+## Decision header
+
+- Initiative:
+- Workflow:
+- Population and scope:
+- Intervention mode: assist / recommend / route / execute / replace
+- Decision sought: scale / constrain / redesign / hold / retire / exception
+- Accountable decision owner:
+- Review date or trigger:
+- Record version:
+
+## Value hypothesis
+
+> For [population] doing [workflow], [intervention] will change [outcome] by [direction/range] without exceeding [countermetric boundary], at [full cost boundary], compared with [baseline], over [period].
+
+- Hypothesis status: supported / weakened / refuted / unresolved
+- Expected benefit:
+- Enabled capacity:
+- Operational benefit:
+- Realized economic or mission benefit:
+- Benefit realization mechanism:
+- Human-control boundary:
+- Authority proposed for next slice:
+
+## Evidence comparison
+
+- Baseline:
+- Comparison design:
+- Treatment period:
+- Comparison period:
+- Inclusion and exclusion rules:
+- Known selection effects:
+- Concurrent changes:
+- Quality measurement limitations:
+- Statistical or causal analysis owner:
+
+| Claim | Class | Source | Result | Caveat | Permitted interpretation |
+|---|---|---|---|---|---|
+| | observed / causal / inferred / vendor-reported / asserted / normative | | | | |
+
+## Outcome and countermetrics
+
+| Metric | Type | Definition and denominator | Baseline | Observed | Target/boundary | Owner | Evidence source |
+|---|---|---|---:|---:|---|---|---|
+| | primary / leading / countermetric / adoption | | | | | | |
+
+## Segment review
+
+| Slice | Adoption or exposure | Outcome | Quality/countermetric | New burden or benefit | Decision implication |
+|---|---:|---:|---:|---|---|
+| | | | | | |
+
+Slices not available and why:
+
+## Cost boundary
+
+### Billing truth
+
+- Provider/infrastructure source:
+- Billing period and version:
+- Reconciliation status:
+
+### Allocated cost
+
+- Allocation target:
+- Shared-cost rule:
+- Allocation owner:
+
+### Economic cost
+
+- Meaningful unit:
+- Model/inference:
+- Tools and APIs:
+- Retrieval/storage/networking:
+- Human review and exception handling:
+- Incremental capacity:
+- Engineering, evaluation, observability, governance, training, support, and exit:
+- Fixed, variable, step-function, avoided, transferred, and uncertain costs:
+- Calculation and allocation method:
+- Range or sensitivity:
+
+## Findings and gaps
+
+### Supported findings
+
+1.
+
+### Unresolved or conflicting findings
+
+1.
+
+### Missing evidence
+
+| Gap | Why it matters | Owner | Next evidence | Due date or trigger |
+|---|---|---|---|---|
+| | | | | |
+
+## Governance evidence packet
+
+- Intended use and risk tier:
+- System/model/prompt/policy/tool/provider/version inventory:
+- Acceptable-use, refusal, escalation, and human-oversight rules:
+- Pre-deployment evaluation and release threshold:
+- Third-party/provider assessment and contractual evidence:
+- Incident, override, and near-miss record:
+- Change/revalidation trigger:
+- Retention, dependency, leakage, user-impact, and decommissioning plan:
+
+## Decision and controls
+
+- Disposition:
+- Scope of approval:
+- Authority limit:
+- Budget or quota limit:
+- Human review or escalation rule:
+- Stop trigger:
+- Rollback, containment, or retirement path:
+- Exception approver, if applicable:
+- Revisit condition:
+
+## Learning closure
+
+- Expected versus observed outcome:
+- Expected versus observed cost:
+- Countermetric and subgroup result:
+- Incidents, overrides, or near misses:
+- Changes since prior record:
+- Hypothesis update:
+- Follow-up artifact or owner:

llms.txt

@@ -10,6 +10,7 @@
 - [agent-production-operations](agent-production-operations/SKILL.md): Operate an evaluated agent with tools and authority in production through a runtime control plane covering versioning, staged rollout, fallback, cost and latency budgets, tool health, human escalation, disablement, and trace-to-eval feedback. Do not use for building agents, designing evals, or general release, SRE, security, or platform engineering — those methods stay with their specialist skills.
 - [agent-skills](agent-skills/SKILL.md): Use this skill when creating, reviewing, or editing Agent Skills-format skills, or when implementing skill discovery and loading in an agent client. It covers directory structure, SKILL.md metadata, progressive disclosure, evals, and repository conventions. Do not use this skill for general software work that does not involve the Agent Skills format or lifecycle.
 - [ai-governance](ai-governance/SKILL.md): Design and operate an organization's AI governance system: define governance principles, operating models and decision rights, risk frameworks, lifecycle gates, and fairness, transparency, privacy, security, regulatory, and board-oversight controls. Use when standing up a governance program, tiering AI use-case risk, reviewing an LLM or agent system for governance and safety gaps, mapping a regulation to a compliance plan, scoring governance maturity, or preparing board reporting. For regulated life-sciences use cases, also cover GxP, ALCOA+, data integrity, electronic records, validation/assurance, and QMS interfaces. Do not use for interpreting regulations as legal advice (route to legal-strategy), data-governance mechanics (data-architect/data-engineering), or implementing application security (secure-software-engineering).
+- [ai-operating-economics](ai-operating-economics/SKILL.md): Use when deciding whether an AI-enabled workflow should be adopted, scaled, constrained, redesigned, or retired, and the decision must connect business outcomes, worker or user effects, quality guardrails, full operating cost, telemetry, uncertainty, and accountable governance. Do not use for a standalone financial model, infrastructure cost calculation, agent evaluation design, runtime operations, or general AI governance; route those details to the neighboring specialist skills.
 - [anydoc](anydoc/SKILL.md): Convert Word (.doc/.docx/.docm), PowerPoint (.ppt/.pps/.pot/.pptx/.pptm/.ppsx/.ppsm), Excel (.xls/.xlsx/.xlsm/.xlsb), OpenDocument (.odt/.ods/.odp), RTF, EPUB, CSV, and PDF documents to clean GitHub-Flavored Markdown locally with the Any Doc CLI (npx -y @firecrawl/anydoc@0.1.6): headings, GFM tables, slide structure, and footnotes in one pass. Use when a task needs the contents of an office document, spreadsheet, presentation, ebook, or PDF you cannot read directly. Do not use for generating, editing, or validating documents (use documents), for ebook packaging (use epub), or for OCR of scanned or image-only PDFs (anydoc does not OCR; route to OCR tooling).
 - [api-design-and-evolution](api-design-and-evolution/SKILL.md): Design, govern, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; assessing an API landscape, ownership, duplication, lifecycle, discoverability, retirement, gateways, service meshes, north-south or east-west traffic, routing, policy, observability, or failure boundaries; defining schemas, pagination, mutations, errors, idempotency, or compatibility; or planning versioning, deprecation, and migration. Do not use for product discovery, platform operations, full security assessment, ADR authoring, or delivery gates; route those to the neighboring specialist skills.
 - [artifact-pyramids](artifact-pyramids/SKILL.md): Organize durable agent research outputs as summaries, analysis, and evidence dossiers. Use when producing multi-layer research artifacts or coordinating research handoffs.

references/skill-triggers.md

@@ -27,6 +27,7 @@ Each skill's `description` field is the canonical routing contract. This conveni
 | "enterprise architecture", "enterprise capability map", "capability mapping", "value-stream architecture", "application portfolio", "information portfolio", "business technology alignment", "current-state architecture", "target-state enterprise architecture", "transition architecture", "enterprise architecture operating model", "cross-domain architecture decision rights", "enterprise architecture governance", "architecture stakeholder engagement" | [enterprise-architecture](../enterprise-architecture/SKILL.md) |
 | "data architecture", "data platform", "data strategy", "data mesh", "governance" | [data-architect](../data-architect/SKILL.md) |
 | "AI governance", "AI governance program", "responsible AI", "model risk", "AI risk tier", "AI risk tiering", "use-case risk tier", "governance operating model", "AI decision rights", "AI governance council", "AI risk framework", "NIST AI RMF", "ISO 42001", "AI lifecycle gate", "AI fairness review", "AI transparency", "explainability review", "LLM governance review", "agent safety review", "prompt injection governance", "AI regulatory compliance", "EU AI Act", "AI compliance plan", "GxP AI governance", "ALCOA+", "data integrity governance", "computerized system validation", "AI in regulated life sciences", "AI QMS interface", "governance maturity assessment", "AI board reporting", "board AI governance", "third-party AI due diligence", "model card" | [ai-governance](../ai-governance/SKILL.md) |
+| "AI value realization", "AI ROI", "AI business case", "AI productivity claim", "AI savings claim", "AI adoption decision", "AI pilot review", "AI workflow economics", "AI cost and value", "AI operating economics", "scale an AI pilot", "retire an AI workflow", "worker impact of AI", "AI countermetrics", "AI total cost of ownership", "AI lifecycle value review" | [ai-operating-economics](../ai-operating-economics/SKILL.md) |
 | "de-spin", "is this spin", "propaganda", "misdirection", "true lies", "what is this leaving out", "misleading claim", "selective framing", "evidence theater", "separate what is true false complicated" | [de-spin](../de-spin/SKILL.md) |
 | "digital twin", "digital twins", "digital twin universe", "digital thread", "software process twin", "DevOps twin", "cyber-cyber twin", "twin architecture", "twin synchronization", "twin fidelity", "twin health", "twin drift", "predictive maintenance twin", "virtual commissioning", "agentic software factory", "dark factory" | [digital-twin](../digital-twin/SKILL.md) |
 | "daily check-in", "day debrief", "conversational journaling", "grill me", "interview me about my life", "learn how I work", "what could an AI help me with", "personal AI boundaries", "proactive check-in", "daily life" | [daily-life-discovery](../daily-life-discovery/SKILL.md) |