zhnnky329/MathModeling-skills

# Workflow

1. Inspect target code extensions and the implementation target in `qx_code_plan.md`.
2. Route `.py` work to `python-code-reviewer`.
3. Route `.m` work to `matlab-code-reviewer`.
4. If both languages are intentionally present, review each separately.
5. If the language or target is ambiguous, report the exact conflict.

# Review Contract

New reviews write JSON and evaluate these named checks:

- `syntax`
- `input_contract`

# Purpose

Check deliverable evidence, not whether every invoked skill left a ceremonial report.

# Lean Checks

Per active Qx, require as applicable:

- manifest;
- method card;
- human decision ledger;
- risk-probe summary;
- latest run summary.

# Modes

- `scoped`: run only for a `CANONICAL` or `FROZEN` change and only for affected Qx/identifiers.
- `final`: run across all submission artifacts before assembly.

# Sources of Truth

Prefer:

- `frozen_numbers.json` for paper numbers;
- `qx_decisions.jsonl` for human judgments;
- `planning/symbol_table.md` for symbols/units;
- approved code plan and run summary for parameters and executed methods;
- solution package for writer-facing structure.

# Purpose

Create traceable cleaned data and one reusable profile. Do not repeat the same data inspection separately for every candidate method.

# Preconditions

- Problem parse and subquestion IDs exist.
- Raw files are available under `workspace/data_raw/` or the workspace's documented legacy raw-data path.
- Required outputs and known field needs are available.

Stop rather than fabricate a missing attachment, unit, field meaning, or label.

# Workflow

# Purpose

Ask the smallest useful question that only the human modeler can answer. Present mutually exclusive options with consequences; do not turn mechanical checks into user questions.

# Inputs

- Current gate and the judgment it needs.
- Problem goal, required output, hard constraints, and available evidence.
- `planning/session_config.json`.
- Existing decisions in `methods/Qx/qx_decisions.jsonl`.

# Configuration

- Read `interaction_mode`; accept legacy `mode` for compatibility.

# Purpose

Make every visual evidence-bearing. Prefer fewer useful visuals over a decorative inventory.

# Inputs

- method card and decision ledger;
- run summaries and final result analysis;
- robustness evidence;
- solution package and frozen numbers in submission mode;
- existing figures/tables.

# Figure Types

# Purpose

Explain the selected method completely without re-authoring why the human chose it.

# Preconditions

- `rigor_profile` is `submission` or writer handoff is explicitly requested.
- Human method choice and result verdicts are recorded in `qx_decisions.jsonl`.
- Approved code ran and final result/robustness evidence exists.

# Sources

Use:

# Preconditions

- Figure type, source artifacts, and target claim are known.
- Type 3 claim is human-confirmed.
- Submission figures use final/frozen evidence.

# References

Load only what the requested chart needs:

- `references/chart-patterns.md`
- `references/color-systems.md`
- `references/layout-guide.md`
- `references/render-check.md`

# Preconditions

- MATLAB code and `code/matlab/Qx/qx_code_plan.md` exist.
- Approved decision, method card, data profile, and run summary are available.
- MATLAB or 北太天元 runtime availability is known.

# Workflow

1. Resolve approved main/baseline scope and any activated fallback.
2. Inspect and run the code when a compatible runtime is available.
3. Evaluate:
   - `syntax`
   - `input_contract`
   - `method_alignment`

# Preconditions

- G2.5 human method choice is recorded.
- `code/matlab/Qx/qx_code_plan.md` exists.
- Required cleaned data and profile exist.
- The plan targets MATLAB or 北太天元.

Legacy artifacts may be read during migration but do not override the human decision.

# Workflow

1. Read the code plan, decision ledger, method card, probe conditions, and data profile.
2. Confirm scope: approved main plus usable baseline. Implement a fallback only after activation.
3. Generate conservative `.m` files under `code/matlab/Qx/`.

# Purpose

Convert the framed problem and data profile into a small executable decision surface. Screen methods for load-bearing data, assumption, degeneracy, sensitivity, and scale risks before asking the human to choose.

This skill proposes and probes methods. The human chooses the method.

# Preconditions

- G1 problem framing passed.
- Required output and evaluation criteria are known.
- Relevant data inventory or audit exists.
- `planning/symbol_table.md` and `planning/model_assumptions.md` exist when the problem needs them.

If these are missing, return to the producer skill rather than guessing.

# Inputs

- problem parse;
- active method cards;
- data profile and risk-probe summaries;
- question dependency map;
- existing assumptions and human decisions.

Read legacy candidate pools only during migration.

# Workflow

1. Extract explicit problem assumptions and method-induced assumptions.
2. Remove filler statements that do not affect model validity or interpretation.

# Purpose

Define exactly what code must implement and save. Do not expand the approved experiment scope or fully plan a dormant fallback.

# Preconditions

- `methods/Qx/qx_method_card.md` and probe summary exist.
- `methods/Qx/qx_decisions.jsonl` contains a human `DECIDED` method choice.
- A usable baseline is identified.
- Cleaned data and `data_profile.json` are ready when data is required.
- Implementation target and round are known.

Read legacy candidate/decision artifacts only when the new artifacts are absent.

# Purpose

Make human judgment traceable without multiplying decision files.

# Canonical Output

`methods/Qx/qx_decisions.jsonl`

One JSON object per line. Records are append-only.

Use `planning/framing_decisions.jsonl` for global/pre-Qx framing decisions.

# Required Fields

# Purpose

Polish mathematical modeling contest paper sections for language quality, logical clarity, formula consistency, and claim calibration.

This skill operates on already-drafted paper sections. It improves wording, fixes grammar, checks formulas, calibrates hedging to match evidence strength, detects overclaims, and ensures formatting compliance. It does not invent new content, add unsupported claims, or rewrite the paper's scientific argument.

Adapted from [nature-polishing](https://github.com/Yuan1z0825/nature-skills) design principles: language serves the argument, polish should not hide weak reasoning, and claims must be proportional to evidence.

This skill does not write new paper sections, run experiments, generate figures, or perform final QA.

# When to use

Use this skill:

# Preconditions

- `rigor_profile` is `submission`.
- Final method explanation exists.
- Final result analysis exists.
- Solution package and current frozen numbers exist.
- Required human claim-scope and physical/domain-meaning decisions are recorded.

If any prerequisite is missing, return to its producer rather than drafting around the gap.

# Primary Sources

Use, in order:

# Preconditions

- `planning/parse/problem_parse.json` exists and maps every Qx to an output.
- Material framing ambiguities are visible.

Read legacy parse paths only during migration.

# Task Types

- evaluation/ranking;
- prediction/estimation;
- optimization/decision;
- mechanism/dynamics;
- classification/clustering;

# Purpose

Produce a model-neutral problem contract. Do not start from favorite algorithms or infer missing attachments.

# Inputs

- complete problem statement and attachments list;
- contest rules and required deliverables;
- user clarifications;
- existing parse when revising.

# Workflow

1. Record source files and missing referenced material.

# Preconditions

- Python code and `code/Qx/qx_code_plan.md` exist.
- Approved method decision, method card, data profile, and relevant run summary are available.
- Required inputs are accessible.

# Workflow

1. Resolve the approved main and usable baseline. Flag scripts for unapproved candidates unless a fallback activation exists.
2. Inspect and run the code in the intended order.
3. Evaluate required checks:
   - `syntax`: imports, execution, exceptions, and obvious runtime faults.
   - `input_contract`: paths, fields, units, shapes, missing-data handling, and raw-data protection.
   - `method_alignment`: formulas, objectives, constraints, assumptions, main/baseline roles, and fallback scope match the approved plan.

# Preconditions

- G2.5 human method choice is recorded in `methods/Qx/qx_decisions.jsonl`.
- `code/Qx/qx_code_plan.md` exists.
- Required cleaned data and profile exist.
- The plan targets Python.

Legacy method pools and `code/model-code-analyzer.md` may be read during migration, but they do not override the human choice.

# Workflow

1. Read the code plan, decision ledger, method card, probe conditions, and data profile.
2. Confirm scope:
   - one approved main method;

# Preconditions

- `rigor_profile` is `submission`.
- All Qx reached G5.
- Final consistency and completeness audits exist.

# Audit Dimensions

1. **Workflow integrity**
   - G1–G5 passed per Qx.
   - Human judgments trace to the decision ledger.
   - Main/baseline/fallback execution respected approved scope.

2. **Evidence integrity**

# Purpose

Manage and verify references for mathematical modeling contest papers.

This skill checks that every cited reference corresponds to an actual source, verifies that citations are placed where evidence is needed, generates properly formatted BibTeX entries for all references, and ensures that the paper does not contain fabricated citations.

This skill does not search for new papers, write paper sections, select methods, or perform QA on modeling content.

# When to use

Use this skill:

- After `paper-section-writer` has drafted paper sections with citations.
- Before `quality-assurance-auditor`.

# Purpose

Analyze user-provided papers and reports before final method selection.

This skill checks whether the user has placed original paper files under `workspace/papers/`, reads those originals, and extracts transferable method cues, assumptions, variables, validation ideas, and limitations for the current subquestions.

This skill does not fabricate references, browse for new papers, write the final method card, or copy a published model blindly.

# When to use

Use this skill:

- After `problem-parser` and `problem-classifier` have produced validated artifacts.
- Before `method-selector`.

# Purpose

Turn saved experiment artifacts into compact evidence. Do not treat ordinary successful runs as requiring a long report, and do not choose the winning method.

# Inputs

- `run_summary.json`
- method card and probe summary
- decision ledger
- saved tables, metrics, and figures
- session `rigor_profile`

Stop if the run summary claims outputs that do not exist or if main and baseline are not comparable.

# Purpose

Test the claims most likely to fail. Choose checks from the model's assumptions and decision risks rather than filling a generic checklist.

# Preconditions

- Approved main and usable baseline executed.
- Run summary, method card, probe summary, and relevant outputs exist.
- Claim or decision to be tested is known.

# Workflow

1. Identify load-bearing assumptions and claims.
2. Select applicable checks:

# Purpose

Create the writer's single source package and immutable numerical snapshot. Do not manufacture missing judgments or freeze unapproved claims.

# Preconditions

- `rigor_profile` is `submission`.
- Final method explanation, final result analysis, robustness report, and figure plan exist.
- Human method, result, stability, and claim-scope decisions exist in `qx_decisions.jsonl`.
- Canonical sources are current.

# Workflow

1. Collect final method structure, result claims, limitations, figures, tables, and decision provenance.

# Purpose

Create one paper Markdown and one `支撑材料/` directory after the submission audits. Preserve selected code, inputs, and outputs under their workspace-relative paths. The packaged code must retain its module imports, CSV parsing, and normal working-directory paths. A packaging manifest stays outside the package at `planning/submission_packaging_manifest.json`.

# Preconditions

- `planning/session_config.json` selects `rigor_profile: submission`.
- Every `planning/manifests/Qx.json` is at G6 and allows final assembly.
- `paper/audits/cross_media_consistency_audit.md`, `paper/audits/completeness_audit.md`, and `paper/qa_report.md` each contain an explicit `Verdict: PASSED` line. Ask the relevant auditor to record the verdict when an older report omits it; do not infer passage from file existence.
- The paper and freezes have not changed after those audits. Renew affected audits when they have.
- Each Qx has a current `frozen_numbers.json`. Its source files identify one successful experiment round; that round's `run_summary.json` lists `scripts`, `inputs`, and `outputs` as workspace-relative paths. Update canonical run evidence through the normal workflow when a field is missing. Never select a round by its number alone.
- A final `paper/main.md` exists, or supply another Markdown with `--paper`.

If the human explicitly authorizes packaging before G6, record their choice and rationale as a `DECIDED` human `packaging_waiver` in a decision ledger. Pass its `decision_id` with `--allow-unaudited`. The package manifest records this waiver and every failed gate or audit; never label it G6-approved.

# Purpose

Ensure the same concept uses one symbol and different concepts do not collide.

# Inputs

- problem parse and relationships;
- active `methods/Qx/qx_method_card.md`;
- approved code plans when available;
- question dependency map;
- existing `planning/symbol_table.md`.

Read legacy candidate pools only when method cards are absent.

# Purpose

Act as the gate-driven scheduler and state reader. Do not solve models, write model code, or draft paper sections.

`../../AGENTS.md` is the packaged policy source. Prefer a project-root `AGENTS.md` when one exists; otherwise read the packaged copy relative to this `SKILL.md`. Apply that policy without reproducing large reports or dashboards.

# Session Start

Before orchestration in a new workspace:

- show `git status --short`;
- check the chosen runtime and required core packages;
- verify the workspace skeleton needed for the current request;
- read `planning/session_config.json`, accepting legacy `mode`.