my-mathmodel-agent

# MathModel Run Use this skill when working on Chinese or international mathematical modeling contest projects that need a reproducible path from problem files to a defensible paper. This is the Claude Code skill entry point. For Codex, use `my-mathmodel-agent/SKILL.md` in the repository root. ## Startup ritual 1. Read `state.json`, `project_manifest.json`, and `PROGRESS.md`. 2. Find the first gate whose value is `false`. 3. Read only the stage contract needed for that gate. 4. Work on one gate at a time and update the durable handoff log. ## Stage machine ```text S0 PREFLIGHT → S1 ANALYZE → S2 ROUTE → S3 DATA_PLAN → S4 METHOD_POC → S5 EXPERIMENT → S6 FREEZE → S7 WRITE → S8 RENDER → S9 AUDIT → READY ``` The required state gates are: ```text input_snapshot problem_decomposed model_route_selected data_plan_ready method_validated experiments_reproduced results_frozen paper_written pdf_verified audit_passed ``` Every gate starts `false`. A gate becomes `true` only after independent, reproducible evidence exists in `audit/gate_evidence.json`. ## Core contracts - Each subproblem gets `planning/problem_analysis.json` with observable acceptance criteria. - Each model route records `baseline`, `primary_model`, `fallback_model`, rejected alternatives, and a validation plan. - Each experiment run records command, input hash, parameters, seed, environment, metrics, logs, and outputs. - Paper numbers may only come from `frozen_numbers.json`. - Each paper claim maps through `paper/evidence_map.json` to a frozen value, figure, or run. - Every PDF page is checked in `paper/render_log.json`. - Final readiness requires zero hard errors in `audit/final_report.md`. ## Role subagents Invoke the role agents under `.claude/agents/`: - `mathmodel-analyst`: decompose problem facts, assumptions, ambiguities, and acceptance criteria. - `mathmodel-modeler`: define symbols, assumptions, objectives, constraints, and model routes. - `mathmodel-coder`: implement reproducible experiments and logs. - `mathmodel-writer`: assemble the paper only from frozen evidence. - `mathmodel-reviewer`: independently reproduce evidence and audit the project. ## Recovery Return to the earliest invalid gate: - question or data scope → S1 - model route → S2 - data leakage or units → S3 - PoC → S4 - experiment or solver status → S5 - numbers → S6 - claim or evidence mismatch → S7 - compile or layout → S8 Use the recorded fallback instead of silently changing the model. Append KEEP/CUT/DEFER/PIVOT/ACCEPT_RISK decisions to `planning/decision_log.jsonl`. ## Completion behavior Do not claim completion because code ran, a solver returned success, or a PDF compiled. Report stage, artifacts, reproduced evidence, risks, and next entry point. Completion requires all gates true and a final independent audit with zero hard errors. For detailed stage instructions, read `my-mathmodel-agent/references/workflow-contract.md`. For machine-readable JSON shapes, read `my-mathmodel-agent/references/artifact-contracts.md`. For final review scoring, read `my-mathmodel-agent/references/evaluation-rubric.md`. When updating a user-requested file, replace the current version at its original path and remove obsolete content or duplicate old versions.