Result Report Generator

Purpose

Generate structured experiment reports and final result analysis for each subquestion based on actual model experiment outputs, figures, tables, and metrics.

This skill converts raw experimental outputs into readable, comparative reports that:

• Explain what each method produced, numerically and visually.
• Compare multiple candidate methods head-to-head on defined metrics.
• Lay out the evidence for whether results are good enough to proceed or need method revision — as an AI suggestion, not a verdict.
• Tell the modeler what to fix or reconsider.
• Tell the paper writer what results are usable, what claims are supported, and what visual evidence exists.

This skill does NOT originate the graded result verdict. It does not assign the per-method [CHOSEN]/[BACKUP]/[REJECTED] label, the round decision (proceed/iterate/return), or the confidence level. Those are the single most graded result-stage judgments — they propagate into the paper and then get frozen. The AI lays out the comparison evidence and an explicitly-labeled [AI-SUGGESTED — not a verdict] read, then STOPS and emits a PENDING decision artifact for the human to render the verdict (see Workflow step 8.5 / Gate G4.5).

This skill does not run experiments, generate figures from scratch, select model methods, write final paper sections, or perform QA.

When to use

Use this skill:

• After one or more candidate methods have been run and produced outputs under results/Qx/experiments/roundN/.
• When the team needs a comparative experiment report to decide which method to keep, drop, or revise.
• When the modeler asks "how did my methods perform?" and needs a structured answer.
• When the programmer has run experiments and needs to produce a structured handoff report for the modeler.
• When results are ready for the paper writer and need to be packaged into a readable narrative.
• When the user says: "generate experiment report for Q1", "compare methods for Q2", "write result analysis for Q3", "is the result good enough for the paper?", or "should I go back and revise the model?".

Preconditions

The following should already exist or be provided:

• A validated method plan with candidate methods defined for the subquestion.
• Experimental outputs under results/Qx/experiments/roundN/ including at minimum:
• Method output files (scores, predictions, plans, etc.).
• Figures saved in the figures/ subdirectory.
• Tables saved in the tables/ subdirectory.
• Metrics saved in the metrics/ subdirectory (if available).
• run_summary.json recording what was run (if available).
• Cleaned data paths and field mappings.
• Expected output definitions from the method plan.

If experimental outputs do not exist, hand back to the appropriate code generator or workflow-orchestrator.

If the method plan is missing, hand back to method-selector.

Inputs

Use or request:

• results/Qx/experiments/roundN/run_summary.json or equivalent execution record.
• Method output files (CSV, JSON, MAT, etc.) under results/Qx/experiments/roundN/.
• Figures under results/Qx/experiments/roundN/figures/.
• Tables under results/Qx/experiments/roundN/tables/.
• Metrics under results/Qx/experiments/roundN/metrics/.
• Logs under results/Qx/experiments/roundN/logs/ if available.
• The method plan for this subquestion (candidate methods, expected outputs, evaluation criteria).
• Cleaning reports or data field mappings if needed for interpreting results.
• Any user notes about method priorities, contest scoring, or expectations.

Workflow

1. Inventory available outputs.

• List every method that produced results in this round.
• List every figure, table, metrics file, and log file.
• Match each output to a candidate method from the method plan.
• Mark missing expected outputs explicitly.

1. Read and interpret each method's results.

• Extract key numerical outputs: scores, rankings, predictions, decisions, error values, objective values.
• Read every figure: explain what it shows, whether the pattern is plausible, whether it reveals a problem.
• Read every table: extract the main takeaway, check for anomalies.
• Read metrics: compare against baseline, check against expected ranges.
• Do not just list file names. Every artifact must be explained.

1. Compare methods.

• Compare all methods in this round on the evaluation criteria defined in the method plan.
• Use a comparison table or equivalent structured comparison.
• State which method performs best on each criterion.
• State trade-offs between methods (speed vs accuracy, simplicity vs precision, interpretability vs fit).
• Do not hide poor performance.

1. Lay out result quality and a SUGGESTED archival read — do NOT assign the verdict labels.

• For each method, present the evidence and your [AI-SUGGESTED — not a verdict] read of whether it looks like a keeper, a secondary backup, or a drop candidate. In the experiment report, tag every per-method line [PENDING-MODELER] — never [CHOSEN]/[BACKUP]/[REJECTED] here. The graded label is the human's to render in the decision artifact (step 8.5).
• Give a concrete reason for each suggested read tied to metrics, visual evidence, or method-plan requirements, so the human's rationale can cite it.
• If a method's output is clearly wrong (infeasible, contradictory, nonsensical), say so plainly with explicit evidence, but still tag it [PENDING-MODELER] and surface it as a strong drop candidate — do NOT pre-stamp [REJECTED].
• Archival is gated on the HUMAN verdict, not on an AI label. Do NOT move any code or outputs in this step. Archival fires only after the modeler tags a method REJECTED in the decision artifact (step 8.5). Once a method carries a HUMAN-tagged REJECTED, then — and only then — move its outputs from the main tree to the archive (the mechanism below is unchanged; only its trigger moved to the human verdict):
• Move code/Qx/_main.py (or .m) → workspace/archived//_REJECTED_roundN/.
• Move its outputs in results/Qx/experiments/roundN/figures/_* and tables/_* → same archive directory.
• Leave a one-line breadcrumb in methods/Qx/qx_method_iteration_log.md (e.g., "Round 1: M3 [REJECTED by modeler decision qxresultverdict] — constraint infeasibility, archived to workspace/archived/Q3/m3REJECTEDround1/").
• The main tree under code/Qx/ and results/Qx/experiments/ should contain ONLY methods the human kept (CHOSEN/BACKUP) after a HUMAN-tagged rejection has been archived. An AI label never triggers archival; a stray AI [REJECTED] in the main tree is itself a workflow defect.

1. Lay out the iteration evidence — do NOT decide the round outcome.

• Present the evidence for whether this subquestion should:
• Proceed to final method selection (results look good enough).
• Return to the modeler for method revision (results look poor or methods need redesign).
• Run another round of experiments (more tuning or alternative methods needed).
• State your [AI-SUGGESTED — not a verdict] read of the round outcome, with the reasoning. The actual round_decision ∈ {proceed, iterate, return} is the human's to render in the decision artifact (step 8.5).
• If your suggestion is "return", state specifically what about the method appears to be failing and what the modeler should reconsider — so the human can act on it.

1. Identify paper-ready materials.

• List which figures and tables can go into the paper directly.
• List which figures and tables need improvement before paper use.
• List which numerical claims are supported by the current results.
• List which claims are not yet supported and what additional evidence is needed.

1. Produce the experiment report (for round N).

• Save as results/Qx/experiments/roundN/qx_experiment_report_roundN.md.
• If this is the final round and results are locked in, also produce the final result analysis.

1. Produce the final result analysis (when all rounds are complete and final method is selected).

• Save as results/Qx/reports/qx_final_result_analysis.md.
• This is the definitive result document for the paper writer.
• Only produce this when the modeler has confirmed the final method in a DECIDED decision artifact (step 8.5).
• You MAY draft the descriptive and interpretive content (what each figure/table shows, what the numbers are). But the verdict/confidence content — which method was chosen, which were rejected, the confidence level, and the round outcome — must be transcribed from the DECIDED decision artifact, not AI-authored. If the artifact is still PENDING, do NOT write the verdict/confidence fields; the analysis is not final.

8.5. Emit the modeler decision artifact, then STOP (Gate G4.5).

• This is the load-bearing change: the per-method verdict, the round decision, and the confidence level are the single most graded result-stage judgments. They propagate into the paper and then get frozen. The AI must not originate them.
• Create methods/Qx/decisions/result-report-generator_modeler_decision.md following the Human Decision Artifact Convention in CLAUDE.md, with:
• decision_id: qx_result_verdict, status: PENDING, decided_by: human (left for the human to confirm).
• ai_suggestion: your read of which method looks best and why, plus your suggested round outcome and confidence — clearly labeled [AI-SUGGESTED — not a verdict], in its own field. This does NOT count as the decision.
• Mandatory HUMAN fields, left as >> sentinels for the modeler to fill:
• per-method choice ∈ {CHOSEN, BACKUP, REJECTED} + a rationale tied to a stated criterion (metric, visual evidence, or method-plan requirement);
• round_decision ∈ {proceed, iterate, return};
• a confidence level per top-line claim, with a rationale that cites a specific computed number.
• rejected_alternatives[*].reason: left as >> for the modeler.
• evidence_refs: point at the real cross-method comparison tables / metrics files under results/Qx/experiments/roundN/ (e.g., the metrics CSV and the experiment report's comparison table) so the human's rationale can cite a concrete computed number. Refs must resolve to real files.
• Then STOP and tell the modeler exactly what to fill in. Do NOT trigger [REJECTED] archival, do NOT finalize the verdict/confidence content of qx_final_result_analysis.md, and do NOT proceed to freeze. Gate G4.5 keeps freeze_allowed_Qx = false until this artifact's status is DECIDED with a non-empty, non-copied human rationale that cites evidence.
• In learning mode (if planning/session_config.json says so): withhold ai_suggestion until after the human writes their rationale, to avoid anchoring. In speed mode: show ai_suggestion alongside. Either way the human fields, their floor, and the copy/evidence checks are identical.

1. Hand off to the appropriate next skill.

• If results need method revision: hand off to final-method-explainer or method-selector.
• If results are final: hand off to final-method-explainer or solution-package-builder.
• If a report is intermediate (round N, more rounds expected): hand off to workflow-orchestrator.

Outputs

Produce the following artifacts as appropriate for the current stage:

• results/Qx/experiments/roundN/qx_experiment_report_roundN.md — Intermediate report comparing all methods run in this round (per-method lines tagged [PENDING-MODELER], not verdict labels).
• methods/Qx/decisions/result-report-generator_modeler_decision.md — PENDING decision artifact (decision_id qx_result_verdict) awaiting the human verdict. Blocks Gate G4.5 — see Workflow step 8.5.
• results/Qx/reports/qx_final_result_analysis.md — Final comprehensive result analysis (only when the decision artifact is DECIDED; its verdict/confidence content is transcribed from that artifact, not AI-authored).

Each report type has different content requirements (see below).

Output format

Round experiment report (qx_experiment_report_roundN.md)

Must contain:

# Qx Experiment Report — Round N

## 1. Execution Summary
- Methods run: [list]
- Execution date/time
- Input data used
- run_summary.json contents summary

## 2. Per-Method Results

### Method M1: [name]  [PENDING-MODELER]
- **Key outputs**: [numerical summary]
- **Figures generated**: [list with one-sentence interpretation each]
- **Tables generated**: [list with one-sentence interpretation each]
- **Metrics**: [values against expected ranges]
- **AI-suggested read** `[AI-SUGGESTED — not a verdict]`: [looks like keeper / secondary backup / strong drop candidate]
- **Reason**: [concrete evidence-based reason the human can cite]
- **Verdict**: `[PENDING-MODELER]` — rendered by the human in `methods/Qx/decisions/result-report-generator_modeler_decision.md` (Gate G4.5). No `[CHOSEN]/[BACKUP]/[REJECTED]` here.
- **Archive action**: none in this report. Archival fires only after a HUMAN-tagged `REJECTED` in the decision artifact.

### Method M2: [name]  [PENDING-MODELER]
...

## 3. Cross-Method Comparison

| Criterion | M1 | M2 | M3 | Best |
|-----------|---|---|---|------|
| [criterion] | [value] | [value] | [value] | [best] |

## 4. Overall Assessment
- **AI-suggested round read** `[AI-SUGGESTED — not a verdict]`: [proceed to final / return to modeler / run another round] — suggestion only
- **If suggesting return to modeler**: [specific issues and suggestions]
- **If suggesting proceed**: [which method looks best and why]
- **Round decision**: `[PENDING-MODELER]` — the human renders `round_decision ∈ {proceed, iterate, return}` in `methods/Qx/decisions/result-report-generator_modeler_decision.md` (Gate G4.5). The freeze stays blocked until then.

## 5. Paper-Ready Materials
- **Can use now**: [figures/tables/claims ready for paper]
- **Needs improvement**: [figures/tables/claims needing revision]
- **Not yet supported**: [claims lacking evidence]

## 6. Recommended Next Step
- [next skill or action]
- [what the next person should do]

Final result analysis (qx_final_result_analysis.md)

Must contain:

# Qx Final Result Analysis

## 1. Method Selection Summary
*(verdict content transcribed from the DECIDED decision artifact `qx_result_verdict`, not AI-authored)*
- Final selected method: [name — from human `choice: CHOSEN` in the decision artifact]
- Eliminated methods and reasons for elimination [from human `choice: REJECTED` + rationale]
- Selection criteria and how the final method performed on each [descriptive — AI may write; the *which-was-chosen* is the human's]
- Decision provenance: `methods/Qx/decisions/result-report-generator_modeler_decision.md` (status DECIDED, decided_by human)

## 2. Final Results
- **Key numerical outputs**: [comprehensive results]
- **Final figures** (with path and interpretation):
  - [figure path]: [what it shows, what claim it supports]
- **Final tables** (with path and interpretation):
  - [table path]: [what it shows, what claim it supports]

## 3. Result Quality Assessment
- **Confidence level**: [high / medium / needs caution — transcribed from the human `confidence` field in the decision artifact, NOT AI-assigned]
- **Limitations**: [what this result cannot claim — descriptive, AI may write]
- **Stability**: [known from robustness checks or flagged as unchecked — descriptive, AI may write]

## 4. Paper Writing Support
- **Supported claims** (ready for paper):
  - [claim] — supported by [evidence]
- **Claims to avoid or qualify**:
  - [claim] — not fully supported because [reason]
- **Figure placement suggestions**:
  - [figure] → recommended section [section name]
- **Table placement suggestions**:
  - [table] → recommended section [section name]

## 5. Handoff
- **Ready for**: [final-method-explainer, solution-package-builder, or paper-section-writer]
- **Pending

…

## Source & license

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

- **Author:** [zhnnky329](https://github.com/zhnnky329)
- **Source:** [zhnnky329/MathModeling-skills](https://github.com/zhnnky329/MathModeling-skills)
- **License:** MIT

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