Figure Table Planner

Purpose

Plan figures and tables for a mathematical modeling contest solution, classifying each visual by its audience and purpose.

This skill determines which figures and tables are needed, what claim each artifact supports, which subquestion it belongs to, which data or result artifact it should use, which of four audience categories it falls into (diagnostic, comparison, paper, appendix), and where it should appear in the paper.

This skill ensures that visual materials serve the modeling logic rather than decoration, and that different audiences (modeler, method selector, paper reader) get the right visuals.

This skill does not fabricate data, generate unsupported figures, write final paper sections, or perform final QA.

B-layer posture — the AI drafts, the modeler owns the claim. Two spans in this plan are interpretive modeling judgments a judge grades, not mechanical bookkeeping: (a) the figure TYPE (1 诊断 / 2 对比 / 3 论文 / 4 附录) — what audience and purpose a figure serves — and (b) the core_claim — the single conclusion a figure is asked to defend in the paper. The AI may DRAFT both, but it must not FINALIZE either on the modeler's behalf:

• The AI proposes a type as [AI-DRAFT — modeler must confirm: ]. The human ratifies or changes it.
• For any Type 3 (论文图) figure — every figure that enters the paper — the AI must NOT author the claim. It writes [MODELER INPUT NEEDED: what single claim does this figure defend?] and stops there. A figure's claim is the sentence a judge weighs the figure against; the human authors it.
• These sentinels ([AI-DRAFT, [MODELER INPUT NEEDED) are exactly like the C-layer >> sentinel: a surviving sentinel in a finalized plan is a GATE FAIL. completeness-auditor treats them as "not done". See Rules and Verification.

When to use

Use this skill:

• After robustness-checker has produced usable robustness evidence.
• After model results, baseline comparisons, and major validation outputs exist.
• Before paper-section-writer.
• When the team needs a figure and table plan for the paper.
• When existing figures or tables need to be checked for narrative relevance.
• When the solution needs flowcharts, mechanism diagrams, result plots, comparison tables, or sensitivity tables.

Preconditions

The following should already exist or be provided:

• A validated problem parse.
• Candidate method pool per subquestion.
• Data report and field mapping if data is used.
• Model result tables and figures (generated from experiments).
• Robustness or sensitivity results.
• Existing figure files if already generated.
• Expected paper structure or subquestion order if available.

If model results do not exist, hand back to code-reviewer, python-model-code-generator, matlab-model-code-generator, or robustness-checker.

If robustness evidence is required but missing, hand back to robustness-checker.

Inputs

Use or request:

• workspace/problem/problem-parser/problem_parse.json, if available.
• Candidate method pool files under methods/.
• Final method explanation files under methods/ (if available).
• workspace/data/data_report.md, if available.
• Model result files under results/Qx/experiments/.
• Robustness report and sensitivity tables under robustness/.
• Existing figures under results/Qx/experiments/*/figures/.
• Code review summary if it affects figure reliability.
• Expected paper section list if available.
• User preferences for visual style or contest formatting, if provided.

Figure Type Classification (Four Categories)

Every planned figure MUST be classified into one of four types:

Type 1: 诊断图 (Diagnostic Figures)

Audience: The modeler. Purpose: Diagnose model problems, check assumptions, identify where the model is failing. When generated: During experimentation rounds, before final method selection. Paper use: Usually NOT included in the paper. For internal model debugging only. Examples:

• Residual diagnostic plots (checking error patterns).
• QQ plots (checking distribution assumptions).
• Convergence trace plots (checking optimization convergence).
• Correlation heatmaps of indicators (checking multicollinearity).
• Intermediate computation visualizations (checking calculation correctness).
• Data distribution plots before/after transformation.

Requirements:

• Must help the modeler decide whether to revise the model.
• Should be generated early (round 1 or earlier).
• Save to results/Qx/experiments/roundN/figures/ (not paper figures).

Type 2: 对比图 (Comparison Figures)

Audience: The modeler AND the paper writer (for method selection narrative). Purpose: Compare multiple candidate methods head-to-head, supporting method selection. When generated: During multi-method experiment rounds. Paper use: MAY be included in the paper to demonstrate thorough method selection, or may be referenced in text only. Examples:

• Side-by-side ranking comparison across methods.
• Prediction error comparison across methods (bar chart of RMSE/MAE).
• Method performance radar chart.
• Baseline vs main model overlay plots.
• ROC/PR curve comparison for classification methods.

Requirements:

• Must clearly show which method performs better and on what criterion.
• Must support the method selection narrative in the paper.
• Save to results/Qx/experiments/roundN/figures/; if selected for paper, copy to paper/figures/.

Type 3: 论文图 (Paper Figures)

Audience: The paper reader (contest judges). Purpose: Support the main claims in the paper — final results, model structure, key findings. When generated: After final method is locked in. Paper use: MUST be included in the paper. Examples:

• Final ranking bar chart.
• Final prediction vs actual plot.
• Optimal allocation map or diagram.
• Model workflow/architecture diagram.
• Mechanism schematic.
• Key sensitivity analysis result plot.
• Final result summary figure.

Requirements:

• Must be publication-quality: clear labels, readable fonts, proper legends, high resolution (≥300 dpi).
• Must directly support a paper claim. The claim is the modeler's to author. Because a Type 3 figure enters the paper, its core_claim is a judgment a judge grades — the AI must NOT finalize it. Write the claim cell as [MODELER INPUT NEEDED: what single claim does this figure defend?] and leave it for the human. (The AI may still draft the figure's type/title/source artifact; only the claim is off-limits to author.)
• Must have a complete, informative caption.
• Must be generated from final (not intermediate) results.
• Save to paper/figures/ (final location).

Type 4: 附录图 (Appendix Figures)

Audience: The paper reader (for supplementary reference). Purpose: Provide supplementary evidence, detailed results, or additional validation. When generated: After final method is locked in, when the main paper cannot fit all figures. Paper use: Referenced in main text, shown in appendix. Examples:

• Full set of sensitivity curves (main paper shows only key ones).
• Detailed indicator-by-indicator breakdown.
• Additional scenario results.
• Full convergence plots for optimization.
• Extended error analysis plots.

Requirements:

• Must be referenced from the main text ("see Appendix Figure X").
• Must not contain critical evidence that should be in the main paper.
• Save to paper/figures/ with clear appendix labeling.

Workflow

1. Identify paper claims and evidence needs.

• Determine which claims require visual or tabular support.
• Map claims to subquestions and model outputs.
• Do not plan figures for unsupported claims.

1. Inventory available artifacts.

• List existing result tables, robustness tables, and figure files.
• Classify each existing figure into one of the four types.
• Identify which artifacts are ready to use.
• Identify which artifacts are missing but necessary.

1. Plan structural figures (typically Type 3 or Type 1).

• Plan overall workflow diagrams (Type 3 — 论文图).
• Plan model principle diagrams (Type 3 — 论文图).
• Plan diagnostic structural checks (Type 1 — 诊断图).

1. Plan result figures (classify each).

• Type 3 (论文图): Final ranking, prediction, optimization results.
• Type 2 (对比图): Method comparison for selection narrative.
• Type 1 (诊断图): Residual checks, diagnostic plots.
• Type 4 (附录图): Extended sensitivity, supplementary scenarios.

1. Plan tables (classify similarly).

• Plan symbol tables, parameter tables, data summary tables, model comparison tables, result tables, and sensitivity tables as needed.
• Avoid duplicating the same information in both a table and a figure unless each serves a distinct purpose.

1. Link figures and tables to paper sections.

• Assign every figure or table to a section.
• State what sentence or claim it supports.
• Mark required captions and interpretation notes.
• For Type 2 figures, note whether they go in the method selection narrative or are reference-only.

1. Check visual evidence quality.

• Ensure every planned artifact uses available data, model results, or robustness results.
• Mark artifacts that are missing source data.
• Reject decorative visuals that do not support reasoning.

1. Produce a figure-table plan per subquestion.

• Save as methods/Qx/qx_figure_table_plan.md.
• Keep the plan concise and traceable.
• Include the four-type classification for every figure.

Outputs

Produce per-subquestion figure-table plans:

• methods/Q1/q1_figure_table_plan.md
• methods/Q2/q2_figure_table_plan.md
• methods/Q3/q3_figure_table_plan.md
• methods/Q4/q4_figure_table_plan.md (if needed)

Each plan includes:

• Figure inventory with four-type classification.
• Table inventory.
• Existing vs planned status.
• Paper section mapping.
• Caption requirements.
• Visual risks.

Output format

Each methods/Qx/qx_figure_table_plan.md must follow this structure:

# Qx Figure and Table Plan

## 1. Figure Inventory

### Type 3 — 论文图 (Paper Figures — MUST appear in paper)

The figure **type** is an AI draft the modeler confirms; the **Claim Supported** for every Type 3 figure is `[MODELER INPUT NEEDED: ...]` — the AI must not author it. A surviving sentinel here is a GATE FAIL.

| ID | Title | Type | Claim Supported | Source Artifact | Paper Section | Status | Caption |
|----|-------|------|----------------|-----------------|---------------|--------|---------|
| Fig.X.1 | Final Ranking Comparison | `[AI-DRAFT — modeler must confirm: bar chart / 论文图]` | `[MODELER INPUT NEEDED: what single claim does this figure defend?]` | `results/Q1/experiments/final/tables/m2_scores.csv` | Results Analysis | exists / planned | "Figure X: Final city rankings based on entropy-weight TOPSIS scores..." |

### Type 2 — 对比图 (Comparison Figures — MAY appear in paper)

| ID | Title | Type | Comparison | Source Artifact | Paper Section (if used) | Status | Caption |
|----|-------|------|-----------|-----------------|------------------------|--------|---------|
| Fig.X.2 | Method Comparison: Ranking Overlap | venn/heatmap | M1 vs M2 vs M3 | `results/Q1/experiments/round2/metrics/comparison_metrics.json` | Method Selection or Appendix | exists / planned | "Figure X: Overlap of top-5 rankings across three candidate methods..." |

### Type 1 — 诊断图 (Diagnostic Figures — Internal use, NOT for paper)

| ID | Title | Type | Diagnostic Purpose | Source Artifact | Status |
|----|-------|------|-------------------|-----------------|--------|
| Fig.X.D1 | Indicator Correlation Heatmap | heatmap | Check multicollinearity among indicators | `workspace/data/data_clean/indicator_data.csv` | exists / planned |

### Type 4 — 附录图 (Appendix Figures — Reference from main text)

| ID | Title | Type | Claim Supported | Source Artifact | Status |
|----|-------|------|----------------|-----------------|--------|
| Fig.X.A1 | Full Weight Sensitivity for All Indicators | sensitivity curves | Extended sensitivity analysis (main paper shows top-3 indicators only) | `robustness/Q1/weight_sensitivity.csv` | planned |

## 2. Table Inventory

| ID | Title | Type | Claim Supported | Source Artifact | Paper Section | Status |
|----|-------|------|----------------|-----------------|---------------|--------|
| Table X.1 | Indicator Weights (Entropy Method) | result table | "Indicator weights are objectively determined by data dispersion." | `results/Q1/experiments/final/tables/m2_weights.csv` | Model Construction | exists |
| Table X.2 | Method Comparison Metrics | comparison table | "Entropy-TOPSIS provides better differentiation than equal-weight scoring." | `results/Q1/experiments/round2/metrics/comparison_metrics.json` | Method Selection | exists |
| Table X.3 | Weight Sensitivity Results | sensitivity table | "Top-3 ranking remains stable under ±10% weight perturbation." | `robustness/Q1/weight_sensitivity.csv` | Robustness Analysis | exists |

## 3. Existing vs Planned Summary

- **Existing figures**: [count] (Type 1: [n], Type 2: [n], Type 3: [n], Type 4: [n])
- **Planned figures**: [count] (Type 1: [n], Type 2: [n], Type 3: [n], Type 4: [n])
- **Existing tables**: [count]
- **Planned tables**: [count]

## 4. Missing Artifacts

| Artifact | Type | Reason Needed | Blocking? |
|----------|------|---------------|-----------|
| `paper/figures/q1_final_ranking.png` | Type 3 | Required for Results Analysis section | Yes |
| `results/Q1/experiments/round2/figures/residual_diagnostic.png` | Type 1 | Useful for modeler to check indicator redundancy | No |

## 5. Visual Risks

- [Risk 1: e.g., "Final ranking figure does not yet have publication-quality formatting."]
- [Risk 2: e.g., "Comparison figure only covers 2 of 3 candidate methods."]

## 6. Handoff

- **Next skill**: `paper-section-writer`
- **Ready figures for paper**: [list]
- **Figures needing generation/improvement**: [list]

Table types

Use these table types consistently:

| Type | Purpose | Paper Use | |------|---------|-----------| | symbol_table | Define variables, parameters, units | Always in paper (Symbols section) | | data_summary_table | Describe data fields, quality, transformations | Usually in paper (Data Preprocessing) | | model_result_table | Show final scores, rankings, predictions, decisions | Always in paper (Results Analysis) | | comparison_table | Compare baseline vs main model, or multiple candidate methods | Often in paper (Method Selection or Results) | | sensitivity_table | Show parameter perturbation effects | Always in paper (Robustness) | | parameter_table | List model parameters and their values/sources | Often in paper (Model Construction) |

Rules

• Every planned figure must be classified into one of the four types (诊断图, 对比图, 论文图, 附录图). The type is the modeler's to confirm. The AI may suggest a type, but it writes it as [AI-DRAFT — modeler must confirm: ]; the human ratifies or changes it. The four-type taxonomy and the "Type 1 诊断图 never in paper" rule are unchanged.
• Every planned figure or table must support a specific claim. For every Type 3 (论文图) figure — every figure that enters the paper — the AI must NOT author the claim. Write the claim as [MODELER INPUT NEEDED: what single claim does this figure defend?]. The claim is the one sentence a judge weighs the figure against; the modeler owns it. (For Type 1/2/4 the AI may draft a claim, but a Type 3 claim is load-bearing and human-authored.)
• A surviving [AI-DRAFT or [MODELER INPUT NEEDED sentinel in a finalized plan is a GATE FAIL — identical to a surviving >> in a C-layer decision artifact. completeness-auditor treats these as "not done". Do not strip a sentinel by inventing the human's answer; only the modeler resolves it.
• Every planned figure or table must map to at least one source artifact.
• Every planned figure or table must map to a paper section (Type 1 diagnostic figures may map to "Internal Use Only").

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zhnnky329
• Source: zhnnky329/MathModeling-skills
• License: MIT

Install and usage instructions live in the source repository linked above.