zhnnky329/MathModeling-skills

MathModeling‑skills – An AI‑assisted workflow guardrail for math‑modeling contests

What it is

• A collection of 29 skills (small, reusable AI‑driven components) that together form a strict, auditable pipeline for preparing a math‑modeling contest paper.
• The AI is only allowed to handle mechanical tasks – parsing the problem, cleaning data, generating code, checking reproducibility, freezing numbers, and producing figures. All scientific judgments (choice of model, interpretation of results, narrative) remain with the human team.
• The repository ships as a native plugin for Claude Code and Codex/ChatGPT, so the skills can be invoked directly from a chat session.

Why it exists

• Contest teams often lose points because of workflow slips: mis‑reading the problem, using numbers that were never produced by a script, or forgetting to update the paper after a bug fix.
• MathModeling‑skills inserts hard gates (G1‑G6) that block downstream steps unless the required checks have passed, making those slips hard to hide.

How it works (the pipeline)

Gate	What happens	Who owns the decision
G1 – PROBLEM_FRAMED	problem‑parser, problem‑classifier, related‑paper‑analyzer create a structured problem description.	AI (mechanical)
G2 – METHOD_SCREENED	method‑selector builds a main candidate, a baseline, and an optional fallback; a risk‑probe summary checks assumptions, data coverage, output degeneracy, perturbation sensitivity and scale.	Human (chooses which candidate to adopt)
G2.5 – CHOSEN_BY_HUMAN	The user records the chosen method and justification.	Human
G3 – CODE_AND_EXPERIMENT_REVIEWED	Code generators (python‑model‑code‑generator, matlab‑model‑code‑generator) produce scripts; code‑reviewer writes a JSON review with five named semantic checks.	AI writes the review, human signs off
G4 – RESULTS_FROZEN	result‑report‑generator, robustness‑checker, math‑figure‑generator produce experiment reports and figures; all numbers are written to frozen_numbers.json. Any later change must be logged and re‑frozen.	Human triggers the freeze; AI enforces the rule
G5 – PAPER_SECTION_READY	paper‑section‑writer drafts sections from the frozen snapshot; paper‑polisher cleans language; reference‑manager builds a verified bibliography.	Human drafts, AI assists
G6 – AUDIT_LAYER_PASSED	Three independent auditors (consistency, completeness, quality‑assurance) each must pass before the submission‑packager creates the final archive.	Human must resolve any failures

Key components

• workflow‑orchestrator – central state machine that tracks which gate each sub‑question is on and enforces the “stale‑downstream” rule.
• symbol‑table‑builder – a single shared glossary (symbol_table.md) that all scripts and the paper reference.
• data‑auditor‑cleaner – creates a read‑only raw data folder and a cleaned copy, guaranteeing that raw data is never overwritten.
• model‑code‑generator – deterministic code (SEED = 2026) for reproducibility, supporting both Python and MATLAB (the latter constrained to contest‑compatible features).
• math‑figure‑generator – produces SVG/PNG figures that pass a visual render‑check before being allowed into the paper.
• frozen_numbers.json – the single source of truth for every numeric value that appears in the manuscript; the repository forbids manual edits.
• audit layer – three JSON‑based auditors that must all succeed; they verify cross‑file consistency, presence of all reviewer artefacts, and overall workflow compliance.

Installation & usage

1. Clone the repo and run ./install.sh. The script registers the mathmodeling‑skills plugin for Claude and/or Codex at user, project, or local scope.
2. In a new chat session, send the Initial Prompt (provided in the repo) to bootstrap the workflow.
3. Interact with the orchestrator using natural‑language commands such as:
   • Q2 has experiment report round1 done. Let workflow‑orchestrator decide whether to iterate or lock the method.
   • Use robustness‑checker for Q1. Do not rerun the main model.
   • Run consistency‑auditor, then completeness‑auditor, then quality‑assurance‑auditor.
4. The AI returns JSON files (reviews, audits, frozen numbers) that are saved directly in the project tree; the human reviews them and proceeds to the next gate.

What it is not

• A one‑click paper generator.
• A system that invents data, results, or citations.
• A replacement for the contestant’s scientific judgment.
• A universal solution for every contest – users must still verify that the AI usage complies with the specific contest’s rules.

Who might benefit

• Teams participating in COMAP’s MCM/ICM, CUMCM, or similar university‑level modeling contests that allow disclosed AI assistance.
• Educators who want to teach disciplined, reproducible modeling pipelines.
• Researchers looking for a template to enforce reproducibility and auditability in collaborative data‑analysis projects.

License

• MIT – free to use, modify, and redistribute.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.