mathmod-compute

name	mathmod-compute
description	Mathematical-modeling compute and evidence Skill for coding/execution-capable agents or humans. Use it for data audit, low-cost probe execution, formal computation, targeted reruns, numerical validation, evidence publication, and render-ready quantitative data. It executes the current semantic contract and surfaces conflicts instead of redefining the problem.

MathMod Compute

ROLE

Use this Skill for execution and verification work: inspect real data, write and run code, execute probes, produce formal calculations, validate outputs, and publish evidence that another fresh session can reproduce and inspect. Codex is often a strong host for this work, but no particular host is required.

This Skill does not choose the problem interpretation for itself. Treat the current context/model.md / context/data.md decisions as the semantic contract. If real data or implementation evidence conflicts with that contract, surface the conflict and return the consequential decision to reasoning work rather than silently changing target, unit, split, time semantics, constraints, assumptions, route, or claim strength.

Probe output is diagnostic. It may cause a semantic decision to be reconsidered, but it cannot become formal evidence without a formal rerun.

READ

Start with the smallest sufficient execution context:

1. AGENTS.md and CONTEXT.md.
2. The current handoff, when one exists.
3. Relevant context/model.md sections: target, observation, objective, constraints, assumptions, route and validation intent.
4. Relevant context/data.md sections: units, entity/observation/time/split semantics, leakage risks and checked data facts.
5. context/evidence.md only when repairing/reproducing an existing formal result.
6. Raw data, source, recipes, model audits, and failure patterns only as the task requires.

Do not load all runs/history by default. For existing formal numbers, follow current_run.json to the selected run; do not guess current from timestamps or directory names.

Do not create compute_context.md, host-specific memory files, a second evidence registry, or a handoff database.

DO

The mode names below are task lenses, not a state machine or required sequence:

DATA_AUDIT

Inspect the files/Sheets/columns actually consumed by the code. Check row counts, missingness, duplicates, units, entity/observation/time keys, grouping/split assumptions, and derived variables. Compare observed facts with context/data.md. Record inputs by repository-relative path and hash where the run tooling supports it.

If the data means something different from current semantics, report the discrepancy; do not invent a reconciliation.

PROBE

Execute a cheap, focused experiment designed to answer one diagnostic question. The handoff/probe brief should already identify the unknown, competing interpretations or behaviors, discriminating observation, expected output, and stopping/escalation condition.

Runner-managed probes use runs/probe/<run-id>/ with their real run.json. Cheap ad hoc checks may stay in stdout or diagnostics/; do not create unmanaged directories inside the structured run tree or invent historical receipts afterward. Neither scratch nor probe numbers enter current_run.json or become paper/formal evidence. At full-project handoff, run the default whole-tree lint; a formal-only lint covers only that stated scope.

FORMAL_COMPUTE

Keep shared inputs/modules stable while a formal run consumes them; disjoint output folders do not remove read/write conflicts. Check known active runs before editing shared dependencies. Before adoption, verify the handoff's required outputs using promote_run.py --expect-artifact artifacts/<file> (repeatable), plus nonblank findings and scientific checks. Successful computations need declared scientific artifacts, not just logs; valid empty result files are allowed. Pure derivations belong in semantic evidence, not dummy runs. In autonomous mode the controller alone adopts, serially.

After the relevant semantics/route are confirmed, execute the complete input → model → validation → export chain. Use real argv, fixed inputs, explicit seeds where stochastic, and question/decision references. Put scientific outputs in the run's artifacts/ and write findings.md describing what was implemented, what was validated, what the evidence supports, what it does not support, and important limitations.

REPAIR_RERUN

For a compute-only defect, identify the root cause, make the smallest source/config/input repair, and run a new run-id. Preserve the old run. If the repair changes target, observation/unit, split, core constraint, objective, assumption, route, or model meaning, stop and return that decision to reasoning work before formal rerun.

EVIDENCE_PUBLISH

Publish only from the current successful formal run. Keep context/evidence.md compact: point to the artifact, field/table/row where practical, units, validation, supported and unsupported claims, and limitations. Do not copy run metadata/logs into shared context.

VISUAL_DATA_EXPORT

Export tidy/render-ready data from current formal artifacts for quantitative figures, including labels, units, grouping and uncertainty columns as applicable, plus a source reference. Do not make downstream writing/visual work reopen raw data or reverse-engineer plotted numbers from an image when exact render-ready data can be provided.

RUN CONTRACT

Run competition/scripts/run_experiment.py from the framework checkout and pass the separate contest repository through --root. Each run gets a fresh runs/<kind>/<run-id>/ in that contest repository; do not overwrite an old run.

run.json records the observable run contract, including run/question identity, purpose, source handoff/decision refs, exact argv, cwd, timestamps, exit/status, Git state, environment, inputs/hashes, seeds and artifacts/hashes. Paths are repository-relative and commands are argv arrays, not shell strings.

A successful formal run must also have findings.md before promotion. Promotion writes:

current_run.json["questions"]["QID"] -> runs/formal/<run-id>/

Only a valid successful formal run may become current. Probe, failed, running, incomplete, missing, or unverifiable runs cannot be promoted. Old runs remain for audit.

VALIDATE

Before calling a formal result usable, check the applicable items rather than treating process success as scientific success:

• input files/Sheets/columns and units match the semantic contract;
• entity/observation/time/split behavior matches the intended prediction/decision setting;
• preprocessing and feature construction avoid future, target, and repeated-entity leakage;
• metric/objective definitions match their implementation and interpretation;
• baseline/comparison is meaningful when the claim depends on comparison;
• constraints/invariants hold after transformations and rounding;
• solver status, time limits, gap, feasibility/optimality language, seeds and uncertainty are reported truthfully;
• exported fields/shapes/units are finite and re-readable;
• findings distinguish supported conclusions from extrapolation, causal, or optimality claims the evidence does not justify.

Use these direct routes instead of rediscovering the framework layout:

• data audit or probe execution → data and probe;
• prediction → prediction recipe;
• evaluation → evaluation recipe;
• optimization → optimization recipe;
• mechanism/simulation → mechanism/simulation recipe;
• formal execution → formal compute;
• validation → validation → the relevant model audit → failure patterns;
• existing formal numbers → current_run.json → the selected runs/formal/<run-id>/ → evidence navigation and reproducibility.

Open only the applicable route. Repository recipes, audits, and failure patterns are procedural knowledge, not mandatory model selectors; follow deeper linked material when the task needs it.

WRITE BACK

Put information in its native location:

• checked durable data meaning → context/data.md;
• probe execution/logs/findings → runs/probe/<run-id>/ and a narrow return/handoff;
• formal execution/evidence → runs/formal/<run-id>/, current_run.json, context/evidence.md;
• render-ready quantitative data → visuals/ with an evidence/source reference;
• code → src/ or the project's existing source layout.

A useful compute → reasoning return is small:

What changed
What was observed
What this supports
What this does not support
What remains unclear
Where the evidence lives
Any conflict with current semantics

The code, logs and detailed outputs stay in their artifact locations.

Before formal transfer between people/agents/tools, make sure durable outputs/context are written and use a meaningful Git synchronization point when the environment permits.

Before stopping, reconcile CONTEXT.md, current_run.json, and context/evidence.md: completed work must no longer appear open, and every claimed current result must still point to the selected formal evidence.

CONFLICT / ESCALATION

When context/model.md, context/data.md, the handoff, code, or actual data disagree on a consequential semantic fact:

1. stop affected formal claims;
2. cite the conflicting paths/observations;
3. identify affected questions/artifacts;
4. return the choice/reconsideration to reasoning work or explicitly preserve ambiguity;
5. after the semantic home changes, use a new run-id for affected formal computation.

Pure implementation defects can be repaired without semantic escalation, but must preserve old runs and record the cause/change/validation.

HANDOFF TO WRITING / VISUAL WORK

For quantitative presentation, preserve exact numbers, units, signs, formulas, variable meaning, grouping/time labels, denominators, rounding, uncertainty and claim strength. Writing/visual work may change color, typography, layout, legend, annotation position and visual hierarchy, but must not invent data, change grouping, smooth away inconvenient structure, turn association into causation, feasible into optimal, or probe into formal evidence.

The same person or capable agent may perform reasoning, compute, and writing/visual work; the boundaries above separate scientific responsibilities, not hosts.

Do not add .mathmod, MCP, scheduler, coordinator, claim/lease, transaction, release authority, or a second memory system to perform ordinary Competition compute work.