| name | mathskills |
|---|---|
| description | End-to-end mathematical modeling competition workflow covering problem interpretation, data auditing, model selection, implementation, validation, visualization, paper writing, and final review. Use when an AI assistant needs to solve or review a mathematical modeling problem, process competition attachments, produce reproducible results, or write a Chinese modeling paper. Designed for tool-capable assistants including Codex, Claude Code, Gemini CLI, Cursor, Copilot, and comparable agents. |
Solve Mathematical Modeling Problems
Act as a mathematical modeling teammate. Work from the problem statement and original attachments to reproducible code, frozen numerical results, figures, and a submission-ready paper.
Treat this file as the platform-neutral source of truth. Treat CLAUDE.md as a detailed legacy rulebook and consult it only for details not covered here. Do not assume a particular model vendor, shell, search product, editor, or agent framework.
Operating principles
- Inspect evidence before choosing a model.
- Prefer an interpretable baseline before a complex method.
- Separate observed data, assumptions, derived quantities, and predictions.
- Build a source-grounded evidence map before relying on an external method, domain fact, or novelty claim.
- Never invent data, citations, experimental results, or successful command output.
- Make every reported number reproducible from saved code and inputs.
- Validate against a baseline and at least one failure-oriented test; do not select a method by a favorable metric alone.
- Check physical, statistical, and domain feasibility, not only numerical convergence.
- Keep the user in control of major modeling decisions.
Resolve capabilities portably
Use available capabilities by purpose rather than by product name:
| Need | Preferred capability | Fallback |
|---|---|---|
| Read PDF/DOCX/XLSX/CSV | Native document or structured-data reader | Local Python library |
| Search literature | Web or scholarly search | Ask for sources; mark citation placeholders clearly |
| Execute analysis | Python, R, MATLAB, Julia, or equivalent | Provide runnable code and state that execution was unavailable |
| Render paper | LaTeX or Typst compiler | Produce source and report that PDF compilation was unavailable |
| Inspect figures | Image viewer or screenshot tool | Check dimensions and file existence programmatically |
| Track work | Native task/plan tool | Maintain a concise checklist in the conversation |
Do not silently skip an unavailable capability. State the limitation and continue with the safest useful fallback.
Orchestrate child Skills
Read skills/registry.yaml before starting the workflow. Resolve legacy names to the canonical child Skills and invoke only the blocks required by the current stage:
| Stage | Canonical child Skill | Purpose |
|---|---|---|
| G0 | workflow-orchestration, plan-and-execution | Resolve capabilities, contracts, state, and a bounded execution plan |
| G1 | data-analysis, jupyter-live-analysis | Audit, clean, explore, and characterize attachments |
| G1.5 | literature-evidence | Map sources, verify method claims, and close citation gaps |
| G2 | model-deliberation, plan-and-execution | Compare approaches, run feasibility checks, and lock an executable plan |
| G3 | data-analysis, model-deliberation, jupyter-live-analysis, sql-data-analysis | Implement evidence-backed models and review data queries |
| G3.5 | validation-and-robustness, measured-experiment-loop | Compare baselines, run bounded experiments, and freeze accepted results |
| G4 | scientific-visualization, academic-writing, national-award-paper-style, academic-translation, research-presentation | Generate figures, draft the paper, translate when needed, and prepare a research presentation |
| G5 | academic-writing, national-award-paper-style | Compile and verify manuscript consistency and competition layout |
| G5.5 | reproducibility-audit | Clean-rerun, artifact lineage, and cross-artifact consistency audit |
| G6 | math-modeling-paper-review, national-award-paper-style, reproducibility-audit, then academic-writing | Independently review content, layout, figures, appendices, and accepted findings |
| G7 | academic-humanization, academic-translation, academic-writing, national-award-paper-style, reproducibility-audit | Naturalize or translate prose, then re-run technical, layout, and reproducibility checks |
When native Skill invocation is supported, call the canonical child Skill. Otherwise read its SKILL.md completely and execute it in the current context. Pass a bounded goal, input paths, protected artifacts, required outputs, and acceptance criteria. Validate returned artifacts before advancing.
Do not chain aliases that resolve to the same canonical block. In particular, run academic-humanization once in G7 instead of applying multiple overlapping de-AI aliases sequentially.
Workspace contract
Use the existing workspace when present:
题目/ original problem PDF or DOCX
数据/ untouched source attachments
求解/
求解计划.md
计划/
探索/
数据审计/
实验/
project_state.yaml
data_audit.md
literature_map.md
citation_ledger.csv
artifact_manifest.json
reproducibility_report.md
预处理数据.*
问题一/
问题一_建模报告.txt
code/
结果/frozen_numbers.json
图片/
论文/
论文.tex or main.typ
sections/
论文.pdf
references/ load only the references needed for the current stage
Preserve original inputs. Write generated artifacts only under 求解/ and 论文/ unless the user requests another location. Use relative paths in code so the project remains movable across operating systems.
Run the workflow
G0: Inspect the environment
- List problem files, data files, existing outputs, and available runtimes.
- Detect the operating system and use its native path and shell conventions.
- Check whether Python/R/MATLAB and LaTeX/Typst are available only when needed.
- Never install software or packages without user authorization when installation changes the system.
- Resume from valid existing artifacts; do not overwrite user work casually.
- Create or update
求解/project_state.yamlwith the current stage, user approvals, protected inputs, decisions, artifacts, open gates, and next action. - Record input paths and hashes when practical so a later rerun can distinguish changed data from changed code.
- For a new workspace, run
python scripts/init_project.py <project-root>; before advancing a gate, runpython scripts/validate_project.py <project-root>and report warnings separately from errors. - Load
national-award-paper-styleat project start when the deliverable is a CUMCM/国赛 paper. Create求解/计划/and record the subproblem-to-artifact dependency map, acceptance gates, estimated compute budget, and user approvals. For a long or multi-artifact task, useplan-and-executionto keep the plan bounded and resumable.
G1: Read and triage the problem
- Read every problem document and inventory every attachment.
- Explain the background, decision target, constraints, deliverables, and each subproblem.
- Audit file formats, dimensions, fields, units, missingness, anomalies, and time ranges.
- Distinguish facts in the statement from interpretations and assumptions.
- Classify each subproblem using
references/problem-taxonomy.md. - Consult
references/problem-triage.mdand relevant cases underreferences/case-studies/when the choice of approach is unclear.
Present a task checklist before modeling. If attachments contain data, perform data auditing before the first subproblem.
Use jupyter-live-analysis only for stateful exploration, quick visual checks, and hypothesis generation. Save notebooks or executed-cell exports under 求解/探索/; before a result can be cited, restart and run all cells, record the environment, and transfer the final computation to a deterministic script under the relevant 问题X/code/ directory.
G1.5: Build the evidence map
- Invoke
literature-evidencewhen the solution uses an external method, domain fact, benchmark, dataset description, or novelty claim. - Produce
求解/literature_map.mdand求解/citation_ledger.csv; keep placeholders and unverified records visibly labelled. - Verify the primary method or authoritative source before locking the candidate model. A source may motivate a choice but cannot replace a feasibility check.
- Do not advance when a central claim is supported only by memory, a search snippet, or an unverified citation.
G2: Propose a solution plan
For each subproblem, specify:
- target quantity or decision;
- candidate baseline and main model;
- variables, units, constraints, and assumptions;
- evaluation metrics and validation design;
- expected outputs, figures, and tables;
- dependencies on earlier subproblems;
- principal risks, including leakage and identifiability.
Use the matching document under references/algorithm-library/, the evidence map, and references/experiment_design_framework.md. Favor the simplest method that answers the question credibly.
For each candidate, record a decision matrix covering validity, data fit, interpretability, robustness, computation, and communication. Before a full run, perform a small feasibility check on real inputs or a defensible analytical sanity check. Record the rejected alternatives and the conditions that would reverse the decision.
Write the approved plan and decision log under 求解/计划/. If the task is expected to require iterative implementation, define the smallest verifiable milestones and a stop condition before coding.
G3: Model one subproblem at a time
Before implementation, create 求解/问题X/问题X_建模报告.txt containing:
【一、问题分析】
【二、模型选择】
【三、变量定义】
【四、公式推导】
【五、求解算法】
【六、验证方案与预期结果】
【七、参考文献】
Include a baseline, model-selection rationale, complete symbol definitions with units, derivation of core equations, constraints, algorithm steps, validation design, and 2-3 verifiable references when literature access is available.
Stop for user review after presenting a materially new modeling direction. Implement only after approval. If the user explicitly requests autonomous execution, continue without waiting but record the assumptions and decisions.
Implementation requirements:
- pin or record random seeds;
- avoid train/test leakage and future-information leakage;
- keep preprocessing fitted only on training data where applicable;
- use multiple starts or methods for non-convex optimization when practical;
- assert dimensions, units, bounds, conservation rules, and other invariants;
- compare baseline and main model on the same split or evaluation protocol;
- run a bounded feasibility check before an expensive or fragile implementation;
- keep a run log of successful, failed, null, and exploratory specifications;
- save code, machine-readable outputs, and environment/dependency information;
- save final reported values in
结果/frozen_numbers.jsonwith provenance. - For database-backed attachments, route through
sql-data-analysis: inspect the schema and keys first, validate JOIN cardinality and fan-out, compare row counts before and after each join, use explicit column lists and units, and inspectEXPLAINor an equivalent query plan for expensive aggregations. Save query text and checks under求解/数据审计/.
Consult references/model-formulation-guide.md, references/math_modeling_norms.md, and references/robustness-guide.md as needed.
G3.5: Validate and freeze results
- Invoke
validation-and-robustnessafter a candidate model exists and before using results in the paper. - Compare against a simple baseline under the same protocol. Choose tests appropriate to the problem: blocked or held-out evaluation, repeated seeds, bootstrap uncertainty, constraint checks, perturbation sensitivity, ablation, placebo, or alternative parameterization.
- Include at least one failure-oriented test that could change the recommendation. Record null and failed checks instead of dropping them.
- Write
求解/问题X/结果/validation_report.mdand a machine-readable robustness file. Freezefrozen_numbers.jsononly after the validation gate passes. - Do not alter preprocessing, split, metric, seed, sample, or constraints after seeing a result without recording the change and labelling the analysis exploratory.
- Use
measured-experiment-looponly when the metric, independent guard, search scope, compute/time budget, keep/discard rule, and stopping condition are written before the run. Log every accepted, rejected, failed, and null trial under求解/实验/; never let an experiment loop overwrite protected inputs or frozen results without a recorded promotion step.
G4: Create figures and write the paper
Generate figures only from frozen outputs. Each figure must communicate a specific claim and include units, readable labels, a caption, and an editable vector version when feasible. Avoid decorative complexity and misleading axes.
For CUMCM/国赛 work, use 国赛/template.tex as the default paper template. Copy template.tex, cumcmthesis.cls, YaHei.Consolas.1.11b.ttf, and Fira Code Retina Nerd Font Complete.otf into 论文/; rename only template.tex to 论文.tex. Treat the files under 国赛/ as immutable assets and populate only the copied template. Use the existing 论文/论文.tex only as a legacy fallback for non-CUMCM work or when the user explicitly requests it.
Route detailed work to:
references/nature-figure-guide.mdfor figure design;skills/scientific-visualization/SKILL.mdfor figure selection, generation, and QA;references/paper-writing-rules.mdfor the paper;references/winning_patterns.mdfor successful competition structure;references/format-spec-51mcm.mdwhen that competition format applies.references/national-award-paper-style.md,references/national-award-layout-contract.md, andreferences/national-award-figure-appendix.mdfor CUMCM writing order, layout, figure/table placement, appendix, and code-index rules.- Load
research-presentationwhen the user requests a defense, group-meeting, or paper-sharing deck. Keep every slide claim linked to the same frozen result, figure source, and manuscript section; useacademic-translationfor a requested Chinese-English or English-Chinese academic version while preserving equations, units, citations, and numbers.
Write only after numerical results are stable. Use the existing 论文/sections/ structure. Keep symbols, units, model names, dataset counts, metrics, and conclusions consistent across abstract, body, tables, figures, and appendices. For national-award papers, enforce the corpus-derived pattern of problem-matched sections, explicit assumptions and symbol units, local description-analysis-conclusion text around each figure/table, and an appendix that maps code files to reported results.
For each important result, maintain an artifact path from the frozen result to the table, figure, caption, and paragraph that use it. Do not hand-edit a reported value after G3.5; repair the producing artifact and rerun the downstream checks.
G5: Compile and inspect
- For the default CUMCM template, run XeLaTeX from
论文/twice against论文.tex; keep the class and both bundled font files beside it. - Compile from a clean state when a renderer is available.
- Resolve missing references, fonts, overflow, unreadable figures, and broken equations.
- Inspect the PDF visually, not only by exit code.
- If compilation is unavailable, validate source structure and report the unverified step.
- Read
references/national-award-layout-contract.mdbefore the final compile. Treat the official current competition template as authoritative; historical award papers inform hierarchy and readability, not exact margins, font sizes, page counts, or mandatory section counts.
G5.5: Audit reproducibility
- Invoke
reproducibility-auditafter the first clean compile and again after any blocking revision. - Produce
求解/artifact_manifest.jsonand求解/reproducibility_report.md. - Attempt a clean or isolated rerun from protected inputs. Check seeds, dependency versions, fonts, relative paths, generated-data lineage, frozen-number tolerances, and raw-input immutability.
- Compare the regenerated outputs with the frozen values and then compare the frozen values with all tables, figures, captions, and headline prose.
- A successful LaTeX compile is not a reproducibility pass. Unavailable runtimes, proprietary inputs, and network-dependent steps must be recorded as explicit blockers.
- Do not enter G6 with a blocking reproducibility finding unresolved unless the user explicitly accepts the limitation.
G6: Review the complete paper and revise
Enter this stage only after the complete manuscript exists and G5 has produced a compiled PDF or the best available equivalent.
Invoke the installed math-modeling-paper-review Skill with:
- the complete paper source and compiled
.pdfor.docx; - all problem files under
题目/; - applicable scoring rules, format specifications, or school template;
- frozen numerical results and the paths to reproducible code;
- generated figures, tables, and their source data when available.
Use a project-local case directory such as math-modeling-review-cases/final-paper/. Preserve the original paper and require the review Skill to produce a reviewed same-format copy, issue list, figure inventory, and work/reference_report.md when its capabilities are available.
After review:
- Classify findings as blocking correctness/format issues, evidence-dependent questions, or optional presentation improvements.
- Apply verified blocking fixes to the canonical source under
论文/, not to frozen results or original inputs. - Do not accept a suggestion that changes a model, number, citation, or conclusion without supporting evidence. Ask the user when the required evidence is unavailable or the change is materially judgmental.
- Recompile and visually inspect the revised paper.
- Re-run the review once when blocking findings were changed; do not loop indefinitely.
After any accepted revision, rerun the affected G3.5 validation and G5.5 reproducibility checks before treating the paper as repaired.
If the external Skill is unavailable, fall back to academic-writing plus references/anti_patterns_checklist.md, references/integrity_gate_checklist.md, and references/qa-checklist.md, and record that independent same-format review was unavailable.
Add a dedicated national-award pass for abstract structure, symbol table units, figure/table captions and cross-references, appendix code index, and WPS/PDF visual readability. Classify historical-corpus observations as style options unless the current official rules make them mandatory.
G7: Humanize and perform final verification
Run these reviews before declaring completion:
- Reproducibility: outputs regenerate from original inputs and saved code.
- Numerical consistency: paper values equal frozen values within stated rounding.
- Modeling validity: assumptions, constraints, validation, and uncertainty are justified.
- Data integrity: no undocumented deletion, fabrication, leakage, or label contamination.
- Citation integrity: every citation is real, relevant, and traceable.
- Evidence traceability: every external claim is in the citation ledger and every reported artifact is in the manifest.
- Communication: claims match evidence; figures and tables are readable and necessary.
- Submission quality: required format, page limits, anonymity, and file names are satisfied.
Run academic-humanization once, protecting equations, citations, frozen values, terminology, and LaTeX structure. Then use academic-writing to re-run numerical, citation, structural, and format checks, followed by reproducibility-audit on the changed artifacts. Use references/anti_patterns_checklist.md, references/integrity_gate_checklist.md, references/qa-checklist.md, and the national-award references. Write unresolved limitations plainly instead of hiding them.
Reference routing
Load references progressively. Do not ingest the entire knowledge base.
| Situation | Read |
|---|---|
| Problem classification | references/problem-taxonomy.md, references/problem-triage.md |
| External methods, domain facts, novelty, or citations | skills/literature-evidence/SKILL.md, references/literature-evidence-protocol.md |
| Algorithm selection | matching file in references/algorithm-library/ |
| Formulation | references/model-formulation-guide.md, references/math_modeling_norms.md |
| Experiment design | references/experiment_design_framework.md |
| Validation, sensitivity, ablation, or uncertainty | skills/validation-and-robustness/SKILL.md, references/validation-matrix.md, references/robustness-guide.md |
| Stateful exploration or notebook handoff | skills/jupyter-live-analysis/SKILL.md |
| SQL-backed data, joins, or aggregation | skills/sql-data-analysis/SKILL.md |
| Bounded iterative experiments | skills/measured-experiment-loop/SKILL.md |
| Paper drafting | references/paper-writing-rules.md, references/winning_patterns.md |
| CUMCM/national-award structure, layout, figures, or appendix | skills/national-award-paper-style/SKILL.md, references/national-award-paper-style.md, references/national-award-layout-contract.md, references/national-award-figure-appendix.md |
| Figures | skills/scientific-visualization/SKILL.md, references/nature-figure-guide.md |
| Academic translation or research presentation | skills/academic-translation/SKILL.md, skills/research-presentation/SKILL.md |
| Multi-step implementation planning | skills/plan-and-execution/SKILL.md |
| Reproducibility, artifact lineage, or clean rerun | skills/reproducibility-audit/SKILL.md, references/reproducibility-package.md |
| Complete-paper independent review | installed math-modeling-paper-review Skill |
| Final review | references/qa-checklist.md, references/integrity_gate_checklist.md |
Treat references/external-skills/ as compatibility aliases and retained unique assets, not independent sources of workflow rules. Resolve every alias through skills/registry.yaml so duplicate blocks are never loaded together. Follow the current platform's higher-priority safety and user instructions.
Completion criteria
Declare the project complete only when:
- all requested subproblems have reproducible solutions;
- the central method, domain, and novelty claims have a completed evidence map or explicit unresolved status;
- validation and sensitivity or robustness analysis are appropriate to the claims;
- every accepted result has a baseline comparison and a recorded failure-oriented check;
- the artifact manifest and reproducibility audit pass, or their blockers are explicitly accepted by the user;
- the complete paper has passed the G6 independent review or its documented fallback, and all blocking findings are resolved;
- reported values trace to frozen machine-readable results;
- the paper and figures agree with the code outputs;
- the national-award layout, figure/table, and appendix checks pass when that format applies;
- every appendix code or supplementary artifact is mapped to a reported result and its dependencies;
- the final source compiles, or the missing compiler is explicitly reported;
- remaining limitations and assumptions are documented.