math-modeling-playbook

name	math-modeling-playbook
description	Evidence-gated mathematical modeling workflow for competitions and applied projects. Use for problem decomposition, data auditing, model-family selection, executable Python or MATLAB solutions, robustness analysis, publication-grade scientific figures, argument-first competition-paper writing, reproducibility, and claim-to-evidence tracing.

Math Modeling Playbook

Turn a modeling prompt into a reproducible result and a defensible paper. Optimize for evidence, clarity, and contest time rather than method novelty alone.

Non-Negotiable Rules

• Never invent data, execution results, metrics, citations, or chart conclusions.
• Label the run as formal, demo, or blocked. Formal runs may not silently replace missing data with synthetic data.
• Establish a simple baseline before adding model complexity.
• Keep training, validation, and test information separated; treat temporal and grouped data with structure-aware splits.
• Tie every important conclusion to a result file, table, figure, formula, or verified source.
• Generate quantitative figures from traceable data and code. Never use AI-generated imagery as empirical evidence.
• Record units, assumptions, random seeds, software versions, commands, and input provenance.
• Report uncertainty, failure cases, and claim boundaries.

Operating Workflow

1. Identify the requested scope, available data, time budget, language, and desired deliverables.

2. Classify each sub-question and map dependencies between them.

3. Create or update the modeling workspace. For a new project, run:

   python scripts/init_modeling_project.py PROJECT_DIR --mode formal --questions N
   

4. Advance through the five evidence gates in order:

   • Intake: problem contract and data audit are complete.
   • Method: candidates, baseline, feasibility probe, and selection rationale are recorded.
   • Computation: code actually ran and can be reproduced.
   • Evidence: baseline comparison, robustness evidence, and canonical numbers are frozen.
   • Manuscript: the argument, claims, figures, tables, terminology, units, and citations are consistent.

5. If an upstream assumption, dataset, method, or parameter changes, mark downstream artifacts stale and rerun the affected gates.

6. Audit before delivery:

   python scripts/audit_modeling_project.py PROJECT_DIR
   

7. Deliver the requested artifacts plus unresolved risks and the audit status. Do not present a failed gate as completed work.

Human Decision Points

Pause for the user's decision when:

• two viable methods encode materially different assumptions or trade-offs;
• the selected method is about to replace a working baseline with a substantially more complex route;
• results are ready to be frozen as the canonical numbers used in the paper;
• missing real data would force a switch from formal to demo mode.

If the user is unavailable and time is limited, keep the baseline, document the assumption, and continue only where the choice is reversible.

Reference Routing

• Rapid triage: read references/problem-triage.md and references/task-family-router.md.
• Model selection or upgrades: read references/model-selection.md and references/when-to-upgrade-model-complexity.md.
• End-to-end work: read references/evidence-gated-workflow.md and references/standard-workflow.md.
• Data, leakage, or reproducibility: read references/data-and-reproducibility.md.
• Validation, sensitivity, or uncertainty: read references/validation-playbook.md.
• Scientific figures, multi-panel layouts, or export QA: read references/figure-contract-and-qa.md.
• Code templates: read references/algorithm-templates.md, then inspect only the closest file under assets/code/python/ or assets/code/matlab/.
• Combination models: read references/advanced-model-combinations.md.
• Paper planning or writing: read references/argument-first-paper-writing.md, references/paper-writing.md, and the templates under assets/templates/.
• Time-limited work: read references/competition-timeline.md.
• Prompt design: read references/ai-prompt-patterns.md.

Required Outputs by Request Type

• Triage: sub-question map, task family, objectives, constraints, data needs, 2-3 candidates, baseline, and major risk.
• Model plan: assumptions, mathematical formulation, candidate comparison, baseline, feasibility probe, metrics, validation design, and fallback.
• Code: input contract, executable source, deterministic command, outputs, error checks, and reproducibility record.
• Results: baseline comparison, uncertainty or robustness evidence, limitations, and a claim-evidence map.
• Figure: one-sentence visual message, non-redundant panel map, source-data links, uncertainty/statistics, editable export, and final-size QA.
• Paper: one-sentence argument, section and paragraph jobs, terminology ledger, evidence-backed results, consistent figures/tables, limitations, and no unsupported claims.

Complexity Escalation Test

Add a component only when all are true:

1. The baseline has been executed.
2. Its failure is observable and named.
3. The added component directly addresses that failure.
4. The comparison protocol is fair.
5. The remaining time supports validation.

Otherwise retain the baseline and improve data quality, formulation, diagnostics, or explanation first.