paper-workflow-orchestrator

Full-process orchestrator for paper generation

Global process collaboration constraints (anti-drift for long conversations)

This skill must not be used as an isolated entry point. When the user requests a complete paper, generates Word, continues the process, or is unsure of the stage, first return to paper-workflow-orchestrator to determine the current S0-S8 stage.

Before starting or continuing a formal task of this skill, you must run:

python .claude/skills/paper-workflow-orchestrator/scripts/workflow_guard.py --skill paper-workflow-orchestrator

If the output is [WORKFLOW FAIL] or the report shows status != "PASS", stop this skill and, according to the paper_output/qa/workflow_guard_report.json failed items, backfill the preceding stages; do not continue from memory.
This skill only writes the paper_output/ artifacts within its own contract scope; after completion, you must return to paper-workflow-orchestrator to determine the next step, and use context-memory-keeper to record completed artifacts, blockers, and the next step.
In a long conversation, if the context grows long, the stage is uncertain, or the user invokes skills separately, first run:
```
python .claude/skills/paper-workflow-orchestrator/scripts/workflow_guard.py --status
```
then read paper_output/qa/workflow_guard_report.json、paper_output/preflight_report.json、paper_output/input_manifest.json、paper_output/results/run_manifest.json and the upstream JSON contract of this skill, and continue according to the recommended_skill and next_action in the report.
Before continuing the process, you must treat paper_output/context/workflow_memory.json as a long-term breakpoint record; if its current_step、next_step、recommended_skill and workflow_guard.py --status are inconsistent, the guard report shall prevail.
After completing the artifacts of this skill each time, first return to paper-workflow-orchestrator or run workflow_guard.py --status, then update workflow memory:
```
python .claude/skills/context-memory-keeper/scripts/update_workflow_memory.py
```
after updating, read paper_output/context/workflow_memory.json / .mdto confirm that the next step and recommended skill have been recorded.

Startup gate (must be executed as the first step)

Before entering any subsequent step,mustrun the preflight script with Bash:

python .claude/skills/paper-workflow-orchestrator/scripts/preflight_check.py

Read the exit code,paper_output/preflight_report.json and paper_output/input_manifest.json：

If the exit code is non-zero or status != "PASS" → immediately stop generating any content. Repeat the errors from the report verbatim back to the user, wait for the user to fix the problem_files/ , then rerun the preflight;
skipping the preflight is not allowed; "just write a rough draft first" is not allowed; judging attachment status from impression is not allowed;
After the preflight passes,input_manifest.json will permanently record the role of each attachment (problem statement, raw data, result template, unparseable files, etc.); subsequent skills must read this manifest and must not guess attachment purposes again from file names.
After the preflight passes, proceed step by step according to the stage routing table below.

State gate (executed before the start of each stage)

Before the formal process enters any stage from S1 to S8, you must use workflow_guard.py to check the artifact status up to the current stage. For example, before entering the data stage, check up to S2:

python .claude/skills/paper-workflow-orchestrator/scripts/workflow_guard.py --step S2

The script will write paper_output/qa/workflow_guard_report.json. If the exit code is non-zero or status != "PASS", you must fill in the preceding-stage artifacts according to the failed items in the report; do not skip steps.

Quickstart usage description

scripts/quickstart_run.py is only for installation verification. The placeholder draft it produces is written to paper_output/quickstart/, and a draft file named quickstart_draft.docx is written,will notpass the evidence gate, and must not be publicly claimed as the final draft.

Calling quickstart is prohibited for formal competition problem tasks. If the user says "let me quickly see what it looks like first," ask first: "Do you need a formal draft or just installation verification?" Do not default to quickstart.

scripts/run_all.py is a compatibility prompt for a deprecated command, used only to protect callers of old documents/old scripts; the formal process no longer calls it.

Execution Contract

Upstream input:problem_files/ the competition problem and attachment data in ; optionally read crawled_data/ supplementary authoritative data in .
Required output:paper_output/OUTPUT_LAYOUT.md、paper_output/input_manifest.json、problem_analysis.json、model_route.json、rubric_alignment.json、scoring_strategy.md, data/chart plan, result evidence, evidence gate report,paper_outline.json、final_paper_source.md、final_paper.docx and format check report.
Downstream handoff: this skill is the main entry point, responsible for determining the current stage and routing to other skills; when the user does not know which skill to start with, call it first.
Failure fallback:problem_files/ blocks when empty; when the model route, data plan, or chart generation fails, print a warning and continue, letting QA fall back according to the available contract.

Objective

This skill is the formal entry point, not a "one-click script manual." For a formal competition problem, the Agent should first read the problem, break it down, determine the nature of the attachments, then generate or modify code specific to the current competition problem, run real results, and finally write globally based on a complete evidence chain.
Maintain the core idea of this project: with skills as the main line, string "problem analysis → model selection → data processing → result evidence → QA gate → Agent global writing → final QA" into an executable workflow.
scripts/quickstart_run.py is used only for quickstart, installation verification, and smoke tests; what it generates is a verification draft and does not represent formal competition paper quality.
scripts/run_all.py is deprecated, with only a migration prompt retained, and is no longer used as the execution entry point for formal papers or quickstart.

Entry Routing Rules

When the user says "start generating a mathematical modeling paper," "help me do this mathematical modeling problem," "analyze the competition problem," "use MathModel Skill," or does not know which skill to call, read this skill first.
First determine the user's goal: for a formal paper, follow the full Agent-native process; when only the problem statement, model, data, QA, or main text is needed, route to the corresponding sub-skill.
Do not make the user understand or choose the order of multiple skills; this skill is responsible for explaining the next stage, and after the stage is completed, return to this skill to determine the next step.
If the user is only verifying the installation or running quickstart, you may call:
- python .claude/skills/paper-workflow-orchestrator/scripts/quickstart_run.py
For formal competition problems, do not run the quickstart script first; you should first read the problem statement and attachments, then generate dedicated data processing, modeling, and plotting code for the current competition problem.

Stage Routing Table

Current Goal	Preferred Call
Just starting, only the competition problem has been given, or you do not know which skill to use	`problem-doc-model-selector`
Already have `problem_analysis.json`, need a model route and scoring loop	`modeling-paper-rubric-and-model-selector`
Need external authoritative data	`authoritative-data-harvester`
Need to process attachment data, generate a data/chart plan, or chart templates	`data-cleaning-and-visualization`
Need to generate model results, evaluation metrics, conclusions, and table evidence	`model-code-and-result-generator`
Before entering main text generation, need a task list and gate checks	`quality-assurance-auditor`
Evidence gate passed, need formal drafting, standard formatting, and Word layout	`paper-formal-writer`
Need micro-unit prompt assets, local expansion, or fallback drafts for lower-capability models	`paper-micro-unit-generator`
Already have `final_paper_source.md` or `final_paper.docx`, need final review	`quality-assurance-auditor` + `paper-formal-writer`

Applicable Timing

When the user has already placed the competition problem PDF/Word and attachment data in the project root directory as agreed and needs an automated end-to-end process "from zero to a ten-thousand-word paper."
When part of the calculation or placeholder filling has already been completed, but you want to check whether the overall steps are complete and in a reasonable order, or want to rerun the core workflow.

Constraints (must be followed)

Memory Interaction (required):
- Throughout the entire workflow: As the overall controller, after each key step (after cleaning, after QA, after generation) is completed, you should proactively call context-memory-keeper to update progress, ensuring that if the workflow is interrupted, a breakpoint record remains in Memory.
This skill is the only "entry routing skill" for the entire project. As long as the user requests "generate a complete paper/run the complete workflow", prioritize reading this skill rather than letting multiple skills run in a scattered manner.
If problem_files/ is empty, the competition problem and attachment data must first be completed before running the workflow.
Competition-problem-specific code must be written to paper_output/code/: data processing goes in data_processing/, plotting goes in visualization/, modeling goes in modeling/, checking goes in qa/. Do not write q1_model.py, plotting scripts, or cleaning scripts back to skills/*/scripts/。
The nature of attachments must first be determined: raw data, result templates, explanatory documents, and reference materials must be handled separately. For example, the result*.xlsx result template that the official requirements ask to fill in must not be mechanically cleaned as raw input data, nor may real modeling results be fabricated based on it.
When any sub-problem's evidence_status is missing、needs_real_modeling or scaffold_result_needs_review , the Word document must not be called the final draft; competition-problem-specific code, real charts, tables, metrics, and conclusions must first be completed.
If the user calls other skills separately, the workflow should ultimately still return to this skill or be completed in the order of this skill: cleaning and plotting → QA task list → micro-unit generation → merging.

Formal delivery gate standards (used to judge whether "paper production is complete")

Must pass:quality-assurance-auditor/scripts/evidence_gate.py 's official mode
Must pass:paper-formal-writer/scripts/check_paper_format.py 's formal format gate
Must exist:paper_output/final_paper.docx, but it can only be called a formal draft after both the evidence gate and the format gate pass.
Must exist:paper_output/OUTPUT_LAYOUT.md(explanation of the current project output location)
Must exist:paper_output/input_manifest.json(attachment role classification, to prevent mistaking result templates/explanatory documents for raw data)
Must exist:paper_output/plan/paper_outline.json(formal paper outline contract)
Must exist:paper_output/final_paper_source.md(formal Markdown source draft for Agent global writing)
Must exist:paper_output/step1/problem_analysis.json(structured problem statement analysis)
Must exist:paper_output/plan/model_route.json(model route contract)
Must exist:paper_output/plan/rubric_alignment.json(scoring point mapping contract)
Must exist:paper_output/plan/data_plan.json and visualization_plan.json(data and chart evidence chain contract)
Must exist:paper_output/figure_index.json(chart plan index)
Must exist:paper_output/results/run_manifest.json(modeling code execution ledger, proving results come from actual execution)
Recommended to exist:paper_output/results/model_results.json、metrics.json、conclusions.json(result evidence contract)
Recommended to exist:paper_output/tables/table_index.json and paper_output/tables/(paper table evidence)
Recommended to exist:paper_output/code/README.md and paper_output/code/*/README.md(explanation of the current competition-problem code workspace)
Recommended to exist:paper_output/tasks.json
Recommended to exist:paper_output/ref_check.md
Recommended to exist:paper_output/micro_units/(as prompt assets and validation drafts, not as the formal main workflow)
Suggested to exist:paper_output/figures/ and paper_output/data_cleaned/(for data preprocessing and result analysis figures)

Script list (those actually used by this skill)

scripts/prepare_output_layout.py: output location preparer.
- When to use: before the full workflow starts, in quickstart, installation verification, or when the user asks "where do code/charts/micro-units go".
- What it does: create paper_output/OUTPUT_LAYOUT.md、paper_output/code/、data_cleaned/、figures/、tables/、results/、micro_units/ and other directories, and write the code workspace README.
scripts/quickstart_run.py: quickstart / smoke test executor.
- When to use: quickstart, installation verification, debugging, or when the user explicitly requests verifying only the workflow chain.
- What it does: first prepare the output directory plan → then run problem-doc-model-selector/scripts/analyze_problem.py to generate problem_analysis.json → then run modeling-paper-rubric-and-model-selector/scripts/build_model_route.py to generate the model route and scoring point contract → then generate the data/chart evidence chain contract and perform cleaning and visualization → then generate the model results, metrics, conclusions, and table evidence contract → then run QA to generate the dynamic paper_output/tasks.json → then generate micro-units offline → then merge into paper_output/final_paper.md and paper_output/final_paper.docx。
- Note: the output is a validation draft and does not represent the formal competition paper.
scripts/run_all.py: deprecated migration prompt.
- When to use: when an old command is triggered by mistake, prompt the user to switch to quickstart_run.py or the formal Agent-native workflow.
- What it does: only prints the migration prompt and does not execute the generation workflow.
scripts/workflow_guard.py: S0-S8 status gate checker.
- When to use: before each stage of the formal workflow starts or when the user requests checking the current progress.
- What it does: checks whether pre-check, problem review, model route, data reading report, modeling code, result evidence, evidence gate, formal draft, and format gate are present in order; on failure, writes paper_output/qa/workflow_guard_report.json and returns non-zero.

Prerequisites

The recommended directory structure is:
- Root directory:<项目根目录>
- Problem statement and attachments:problem_files/(place the problem statement PDF/Word and attachment data directly here; QA will check that this directory is not empty)
- Supplementary data:crawled_data/(optional; place crawler or external public data here)
- Output directory:paper_output/(the script automatically generates the task list, micro-units, and merged draft)
- Code specific to the current problem:paper_output/code/(place only the data processing, plotting, modeling, and checking code for the current problem)
- Skill directory:skills/...
Python being available is sufficient.

Input

Required:
- Place the problem statement PDF/Word and attachment data into problem_files/。
Optional:
- Place supplementary data into crawled_data/。

Output

Intermediate files:
- paper_output/OUTPUT_LAYOUT.md: description of the current project's output locations.
- paper_output/code/README.md: description of the code workspace specific to the current problem.
- paper_output/code/data_processing/: data processing code for the current problem.
- paper_output/code/visualization/: plotting and formatted chart code for the current problem.
- paper_output/code/modeling/: q1/q2/q3 modeling code for the current problem.
- paper_output/code/qa/: optional checking code for the current problem.
- paper_output/step1/problem_analysis.json: structured problem analysis, connecting subsequent QA and main text generation.
- paper_output/step1/A_题意对齐.md、B_论文大纲.md、C_评分点对齐表.md、D_模型路线.json。
- paper_output/plan/model_route.json: The model route, validation plan, and suggested charts for each question.
- paper_output/plan/rubric_alignment.json: Mapping of scoring points and evidence.
- paper_output/plan/scoring_strategy.md: Explanation of the scoring loop.
- paper_output/plan/data_plan.json: Data files, field profiles, cleaning tasks, and sub-question links.
- paper_output/plan/visualization_plan.json: Suggested charts, figure titles, purposes, candidate fields, and output paths.
- paper_output/figure_index.json: Chart plan index for QA and main-text citation cross-checking.
- paper_output/results/model_results.json: Evidence contract for each question's model outputs, parameters, solutions, or prediction results.
- paper_output/results/metrics.json: Evaluation metrics, errors, scores, or constraint satisfaction for each question.
- paper_output/results/conclusions.json: Structured conclusions for each question that can be tied back to the original problem.
- paper_output/tables/table_index.json: Paper table index, table titles, purposes, and paths.
- paper_output/tasks.json: Micro-unit task list.
- paper_output/micro_units/*.txt: One file per micro-unit.
- paper_output/generate_log.json: Generation log.
Final deliverables:
- paper_output/final_paper.md: Merged Markdown paper draft.
- paper_output/final_paper.docx: Word draft, as the main deliverable.
- paper_output/ref_check.md: Cross-reference and numbering broken-link report.

Workflow (corresponding to the workflow_full steps)

Formal implementation: Agent-native workflow (recommended)

Read the competition problem and attachments, and determine whether the attachments are raw data, result templates, explanatory documents, or reference materials.
Generate the problem interpretation analysis, model route, scoring loop, data plan, and chart plan.
In paper_output/code/ , generate or modify the data processing, modeling, and plotting code specific to the current competition problem.
Run the specialized code to produce real charts, tables, metrics, and conclusions, and write them back to paper_output/results/ and paper_output/tables/。
Run quality-assurance-auditor/scripts/evidence_gate.py; if it does not pass, continue supplementing evidence and do not proceed to the formal manuscript.
After the evidence gate passes, run paper-formal-writer/scripts/build_paper_outline.py to generate paper_output/plan/paper_outline.json。
The Agent reads paper_outline.json, the complete evidence chain, and prompt assets, and globally writes paper_output/final_paper_source.md。
Run paper-formal-writer/scripts/format_formal_docx.py to generate the formal Word document, then run paper-formal-writer/scripts/check_paper_format.py。
After both the evidence gate and format gate pass, call quality-assurance-auditor again to perform the final consistency check.

Quickstart validation workflow (not the formal paper production workflow)

Output directory planning:
- Call paper-workflow-orchestrator/scripts/prepare_output_layout.py, generate paper_output/OUTPUT_LAYOUT.md and paper_output/code/ workspace instructions.
- This step only establishes the placement specification and does not execute black-box modeling.
Structured analysis of the competition problem:
- Call problem-doc-model-selector/scripts/analyze_problem.py, generate paper_output/step1/problem_analysis.json。
- Solidify each question's task type, recommended model, validation plan, and suggested charts into a data contract that subsequent skills can read.
Model route and scoring loop:
- Call modeling-paper-rubric-and-model-selector/scripts/build_model_route.py, generate paper_output/plan/model_route.json、rubric_alignment.json and scoring_strategy.md。
- If this step fails, the workflow continues, and QA falls back to problem_analysis.json。
External resource acquisition (Optional):
- Call authoritative-data-harvester or g-sci (if present) to populate crawled_data/。
- Memory Update: Update the acquired literature/data sources to memoryskill.md。
Call data-cleaning-and-visualization/scripts/run_pipeline.py: first read input_manifest.json, then generate data_plan.json、visualization_plan.json and figure_index.json; only treat files marked in the manifest as raw_data and the available files as modeling data, produce cleaned data and charts to paper_output/。
Call model-code-and-result-generator/scripts/build_result_contracts.py: generate based on the model route, cleaned data, and chart plan model_results.json、metrics.json、conclusions.json and table_index.json. In real competition problems, the Agent should continue to, in paper_output/code/modeling/ secondary generation or modification of dedicated modeling code, and fill in the real results.
Call quality-assurance-auditor/scripts/pipeline.py: check problem_files/, prioritize generating a dynamic one based on the model route, scoring points, data charts, and result evidence paper_output/tasks.json。
Call paper-micro-unit-generator/scripts/generate_all_offline.py: generate paper_output/micro_units/*.txt and paper_output/generate_log.json。
Call paper-micro-unit-generator/scripts/merge.py: generate paper_output/final_paper.md and paper_output/ref_check.md，and directly generate paper_output/final_paper.docx。
[Mandatory] Word delivery verification:
- Check whether paper_output/final_paper.docx exists.
- Prefer using the Word version directly generated by scripts/merge.py (natively generated with python-docx, does not rely on Pandoc).
- Only when direct generation fails, try calling Pandoc as a fallback.
- Ensure formulas, charts, and table of contents display correctly in Word.

Run in steps (use only when needed)

External resource acquisition:
- If supplementary literature or data is needed, first run authoritative-data-harvester or other search skills.

0.5. Only prepare output directory planning:

python .claude/skills/paper-workflow-orchestrator/scripts/prepare_output_layout.py

Only do data cleaning and visualization:

python .claude/skills/data-cleaning-and-visualization/scripts/run_pipeline.py

1.5. Only generate result evidence contracts:

python .claude/skills/model-code-and-result-generator/scripts/build_result_contracts.py

Only do structured analysis of the competition problem:

python .claude/skills/problem-doc-model-selector/scripts/analyze_problem.py

Only generate the model route and scoring loop:

python .claude/skills/modeling-paper-rubric-and-model-selector/scripts/build_model_route.py

Only generate the task list (will check that problem_files/ is not empty, and prioritize reading model_route.json）：

python .claude/skills/quality-assurance-auditor/scripts/pipeline.py

Only generate micro-units:

python .claude/skills/paper-micro-unit-generator/scripts/generate_all_offline.py

Only merge and generate the paper:

python .claude/skills/paper-micro-unit-generator/scripts/merge.py

Only generate the formal paper outline contract:

python .claude/skills/paper-formal-writer/scripts/build_paper_outline.py

Only format the formal Word:

python .claude/skills/paper-formal-writer/scripts/format_formal_docx.py

Only check the formal paper format:

python .claude/skills/paper-formal-writer/scripts/check_paper_format.py

Common issues

Error "problem_files is empty": put the competition problem PDF/Word and attachment data into problem_files/ and rerun.
Want to see the problem statement breakdown: view paper_output/step1/problem_analysis.json and paper_output/step1/A_题意对齐.md。
Want to see the model route: view paper_output/plan/model_route.json and paper_output/plan/scoring_strategy.md。
Want to see the paper output: the final file is paper_output/final_paper.docx, the intermediate draft is paper_output/final_paper.md。
Want to see the output location plan: view paper_output/OUTPUT_LAYOUT.md。
Want to see competition-specific code: view paper_output/code/, do not look for the current competition code in the skill package directory.
Want to see data and charts: cleaned data is in paper_output/data_cleaned/, charts are in paper_output/figures/。
Want to see result evidence: view paper_output/results/ and paper_output/tables/table_index.json; among them, results in draft status need to be completed with real modeling code.