mathodology-workbench git:20261105.313fcebA

Immutable. This exact content never changes and is served at /api/v1/blob/1b88d4ebffb8896a.

---
name: mathodology-workbench
description: Use when setting up, running or checking a contest workspace, recording experiments, keeping paper numbers, figures and LaTeX consistent with results, or installing the Mathodology hooks.
---

# Mathodology Workbench

The other skills guide judgment; this one executes. `scripts/mtd.py` (Python 3.9+,
standard library only) links the five stages of a contest through files, so each
stage reads what the previous one actually produced:

| Stage | Produces | Executable support |
|---|---|---|
| Problem brief | `problem/questions.json`: per question, deliverables, metrics, inputs, assumptions, dependencies | `mtd.py brief` lists the numbered questions; you fill in the rest |
| Experiments | code under `code/`, a recorded run per execution | `mtd.py run -- python code/q1.py` logs command, seed, inputs, outputs, exit code; placeholder scripts and stub functions are flagged |
| Results | `results/*.json` in the contract below, written by code | validation, provenance and staleness against the code that produced them |
| Figures | images drawn by scripts that read results | traces script → data → image; flags stale, missing, corrupt or low-resolution figures |
| Paper | LaTeX citing `\res{q1.rmse}`, or Markdown citing `{{res:q1.rmse}}` | `mtd.py sync` writes `paper/results.tex` and booktabs tables in `paper/tables/`; checks numbers, refs, cites, figures and the compile log, and math and citations in Markdown |

Run it from the workspace (or pass `--root`); the path below is relative to a
project with the skill installed:

```bash
python3 .claude/skills/mathodology-workbench/scripts/mtd.py init --paper-template   # or --paper-template cumcm
python3 .claude/skills/mathodology-workbench/scripts/mtd.py brief          # after the statement is in problem/
python3 .claude/skills/mathodology-workbench/scripts/mtd.py run --seed 1 -- python code/q1.py
python3 .claude/skills/mathodology-workbench/scripts/mtd.py status        # every stage; --json for tools
python3 .claude/skills/mathodology-workbench/scripts/mtd.py check --compile   # exit 1 on errors
```

A workspace is a folder with `.mathodology/`, or with `problem/` and `paper/` as
Mathodology Studio creates them. Contracts and every check are described in
[references/contracts.md](references/contracts.md).

`--paper-template NAME` starts from a contest skeleton instead of the generic
one: `cumcm`, `mcm`, `stats`, `huawei`, `mathorcup` or `apmcm`. It also sets
`"contest"` in `.mathodology/config.json`, so `check` adds the format rules that
were read in that contest's official text: no table of contents for CUMCM,
the 25-page limit for MCM/ICM, anonymity. The skeletons and checks record the
rules as of the date in [references/contest-formats.md](references/contest-formats.md).
The current official rules always take precedence. For 华为杯, MathorCup and APMCM
the format rules were not verified, so the skeleton only organizes content.

Choose the template from the problem statement and the user's words: the
contest name, the year, the problem letter and the submission instructions
usually settle it. Say which contest you chose before running `init`. Ask the
user, with the agent's question tool when it has one, when the evidence is
unclear or points to a contest without a skeleton (华数杯 and others take
`generic`), and before relying on a skeleton whose rules are unverified. When
`"contest"` is already set, for example by Mathodology Studio's new-project
dialog, keep it unless the user says otherwise. `init` never replaces an
existing `paper/main.tex`.

## Results contract

Experiment code writes one JSON file per question or analysis:

```json
{"schema": "mathodology.results/1", "question": "Q1",
 "values": {"rmse": {"value": 0.0912, "unit": "kWh", "digits": 3, "ci": [0.081, 0.101]},
            "best_cost": 1532.4},
 "tables": {"compare": {"columns": ["model", "rmse"], "rows": [["ARIMA", 0.12], ["ours", 0.091]]}}}
```

In LaTeX, `\input{results}` in the preamble, then write `\res{q1.rmse}`,
`\resci{q1.rmse}` and `\resunit{q1.rmse}`. Each table becomes
`paper/tables/q1-compare.tex`; put `\input{tables/q1-compare}` inside your own
`table` float. A rerun followed by `sync` updates
every number in the paper. Numbers typed by hand are still compared with the
results, allowing for the rounding shown: a value that no longer matches after a
rerun is reported as a near miss.

## Hooks

`mtd.py install-hooks` (also run by `init` and by Mathodology Studio) merges
four Claude Code hooks into `.claude/settings.json`, preserving other settings:

- Session start: a short status of every stage enters the agent's context.
- Before an edit: hand edits to `results/*.json` and the generated
  `paper/results.tex` and `paper/tables/*.tex` are refused; results change by rerunning code. A user who
  really wants manual results sets `"allow_result_edits": true` in
  `.mathodology/config.json`.
- After an edit or command: an edited paper file is checked at once; when a
  command changed results, the contract is validated and the macros refreshed.
- Stop: if errors remain (unknown `\res` key, missing figure, undefined
  citation or reference, invalid results, LaTeX errors in a current log), the
  agent is asked once to fix them or explain why they remain.

`"stop_gate"` in `.mathodology/config.json` is `errors` (default), `warnings`
or `off`. A check that cannot run (no TeX engine, a crashed checker) is a
note and never blocks. Hooks are silent outside a workspace and never fail the session.
Codex, Gemini CLI and other agents do not load these hooks: run
`mtd.py check` before handing over a draft.

## Judgment the checks cannot make

The checks are mechanical. They do not decide whether a model is appropriate,
whether a baseline is fair or whether a claim follows from the evidence; use
[review questions](../mathodology-award-gates/SKILL.md) for that. When the
report and the paper disagree, correct the paper from the results or rerun the
experiment; never edit results to fit the text. A number reported as unmatched
may be a parameter or a literature value: trace it rather than delete it.
Report failed or abandoned runs that matter for the conclusions. Figures follow
[figure presets](../mathodology-figure-presets/SKILL.md); have figure scripts
read results files rather than retyping values so the staleness check works.