Final Method Explainer

Purpose

Help the modeling team member write a definitive final method explanation for a subquestion after multi-round experimentation has converged on the best method.

This skill converts the candidate method pool, iteration logs, and experiment reports into a single authoritative document that explains:

• Which method was finally chosen and why — transcribed from the modeler's logged method_choice rationale, NOT re-authored here.
• Which other candidate methods were eliminated and why — transcribed from the same decision record's rejected_alternatives.
• The full mathematical specification: assumptions, symbols, objective function, constraints, solution procedure. (This structural specification stays AI-drafted.)
• Evaluation metrics — with the good-result threshold supplied by the human decision artifact, not invented by the AI.
• Concrete paper-writing suggestions for the model construction section.

Two graded judgments in this document are NOT originated by this skill: (a) the "why this method was chosen" narrative, and (b) the assumption necessary-vs-simplifying labels, plus what counts as a "good" result. These are decided by the human at Gate G4.5 in a decision artifact; this skill drafts connective prose and a suggested label only, clearly marked, and transcribes the human's verdict once logged.

This skill does not select the final method (the modeler does), originate the why-this-method verdict, originate assumption-necessity labels, run experiments, write final paper sections directly, or generate code.

When to use

Use this skill:

• After one or more rounds of experiments have been completed and the modeler has decided which method to use.
• After result-report-generator has produced experiment reports and the modeler has reviewed them.
• When the modeler needs to produce methods/Qx/qx_final_method_explanation.md.
• When the user says: "write the final method explanation for Q1", "document the final method", "explain why we chose this method", "prepare the method for paper writing".
• Before solution-package-builder or paper-section-writer.
• When the method iteration log shows convergence and the modeler confirms final selection.

Preconditions

The following should already exist or be provided:

• The candidate method pool for this subquestion (methods/Qx/qx_method_candidates.md or equivalent).
• The method iteration log (methods/Qx/qx_method_iteration_log.md or equivalent), recording what changed across rounds.
• Experiment reports from at least one round (results/Qx/experiments/roundN/qx_experiment_report_roundN.md).
• The modeler's explicit confirmation of which method is the final choice — captured as a DECIDED method_choice record in methods/Qx/qx_decision_log.md (collected by modeler-decision-logger). Iteration logs alone are evidence, not the verdict.
• The problem parse and classification artifacts (for subquestion goals, constraints, and required outputs).
• The global assumptions list planning/model_assumptions.md (the source the per-assumption necessity verdict is decided against).

If the candidate method pool does not exist, hand back to method-selector.

If no experiment reports exist, hand back to result-report-generator.

If methods/Qx/qx_decision_log.md has no DECIDED method_choice record for this Qx, the why-this-method narrative has no backing — hand back to the modeler (via method-selector / modeler-decision-logger) before producing the explanation. Do not guess which method is "final", and do not author a "why we chose X" sentence yourself. Do not infer the verdict from experiment results alone.

Inputs

Use or request:

• methods/Qx/qx_method_candidates.md — the original candidate method pool.
• methods/Qx/qx_method_iteration_log.md — the record of method changes across rounds.
• results/Qx/experiments/roundN/qx_experiment_report_roundN.md — experiment reports from all rounds.
• workspace/problem/problem-parser/problem_parse.json — for subquestion goals and constraints.
• workspace/problem/problem-classifier/problem_classification.json — for task type context.
• workspace/problem/method-selector/method_plan.json — for original method specifications.
• methods/Qx/qx_decision_log.md — the canonical decision log. The method_choice record's modeler_rationale is the only source for the why-this-method narrative; transcribe it with `` provenance.
• planning/model_assumptions.md — the global assumptions list against which necessary-vs-simplifying is decided.
• The modeler's explicit confirmation of the final method choice (as a logged decision record, not verbal).
• Any additional notes the modeler provides about why they chose this method.

Workflow

1. Confirm final method selection — from the decision log, not from your own reading.

• Read methods/Qx/qx_decision_log.md for the DECIDED method_choice record. That record's modeler_decision is the final method; its modeler_rationale is the why.
• Read the iteration log to trace the decision path (what was tried, failed, improved, dropped) — as supporting evidence only, not as the verdict.
• If there is no DECIDED method_choice record, stop and hand back to the modeler. Do not promote a method from iteration-log ambiguity.
• Do not independently decide which method is "final", and do not author the why. The human already authored it in the log; your job is to transcribe.

1. Document the selection process — by TRANSCRIBING the human's logged rationale, not re-authoring it.

• State the final selected method clearly (from the method_choice record's modeler_decision).
• List every candidate method that was considered and experimented.
• For each eliminated method, transcribe the reason from the decision record's rejected_alternatives[*].reason (the human's words), tagged ``. The experiment reports supply the supporting numbers, but the judgment "this is why it was dropped" comes from the log.
• The "why the final method was chosen" paragraph is transcribed from the method_choice record's modeler_rationale, carrying a ` provenance comment — NOT composed by you. You may add neutral connective phrasing around the transcribed sentence (and mark any such drafting [AI-DRAFT — needs modeler verdict]`), but you may NOT write a "why we chose X" claim that has no backing sentence in the log. If the log's rationale is thin, that is a gap for the modeler to fill, not for you to paper over.
• Be honest about trade-offs. If the final method has weaknesses, state them explicitly (trade-offs may be drawn from experiment reports and the logged rationale; do not invent favorable ones).

1. Define model assumptions — list and draft, but the necessary-vs-simplifying verdict is the human's (Gate G4.5).

• List every modeling assumption the final method relies on, sourced from planning/model_assumptions.md plus any method-specific ones.
• For each assumption you may suggest a label — "necessary" (the model breaks without it) or "simplifying" (the model works but is more approximate without it) — but mark every such suggestion [AI-DRAFT — needs modeler verdict]. The committed label is decided by the human in the decision artifact (decision_point: assumption_necessity), then transcribed back here.
• For each assumption, state its possible impact on results (AI may draft this factual impact note).
• Link assumptions to the problem context — why is this assumption reasonable for this specific contest problem?
• Do not include generic assumptions that don't affect the model.
• Do NOT present a necessary/simplifying label as settled until it carries the human's verdict from the decision log. The label is graded reasoning; this skill never originates it.

1. Define symbols and notation.

• Create a complete symbol table covering all variables, parameters, sets, indices, functions, and outputs used in the final method.
• Distinguish: decision variables, state variables, parameters, inputs, intermediate values, and outputs.
• Include units where applicable.
• Ensure notation is consistent with other subquestions (check the global symbol table if it exists).
• Mark symbols that are shared across subquestions.

1. Write the mathematical model specification.

• State the objective function (for optimization) or evaluation criterion (for evaluation) or prediction target (for prediction).
• State all constraints in mathematical form.
• State the solution procedure step by step.
• For optimization: define decision variables, objective, constraints, and solver approach.
• For evaluation: define indicator normalization, weighting method, aggregation formula, and ranking rule.
• For prediction: define model form, training procedure, prediction formula, and error estimation.
• For mechanism: define governing equations, parameters, boundary conditions, and solution method.
• For classification/clustering: define features, model form, training/clustering procedure, and assignment rule.
• For simulation: define stochastic elements, trial structure, output statistics, and seed management.
• Every equation must have its variables defined. Every parameter must have a source or estimation method.

1. Define evaluation metrics — formulas are AI-drafted, the good-result threshold is the human's.

• State how this method's output quality is measured.
• Define each metric formula (AI-drafted).
• State expected ranges. The result_good_threshold — i.e., what value of a metric counts as a "good" result for this method — is a graded judgment supplied by the human in the decision artifact; transcribe it, do not invent it. You may suggest a threshold marked [AI-DRAFT — needs modeler verdict].
• Link metrics to the subquestion's evaluation criteria from the problem parse.
• Do not author a "this is a good result" interpretation that has no backing result_good_threshold in the decision artifact.

1. Provide paper-writing guidance.

• State which parts of this explanation should go into the "Model Construction" section of the paper.
• State which formulas are most important to show.
• State which assumptions should be highlighted.
• State which eliminated methods should be mentioned (for demonstrating thoroughness).
• Suggest a logical flow: assumptions → symbols → model formulation → solution → metrics.
• Flag any parts of the explanation that are "for internal use only" and should not appear in the paper (e.g., implementation details, debugging notes).

1. Produce the final method explanation document.

• Save as methods/Qx/qx_final_method_explanation.md.
• Keep it structured, complete, and self-contained.
• The document should be understandable without reading the iteration logs or experiment reports (though it should reference them).
• The structural sections (symbols, math model, solution steps) are AI-drafted as before. The two graded inserts — the why-this-method narrative and the necessary/simplifying labels + good-result threshold — must either carry a ` transcription provenance (already logged) or an [AI-DRAFT — needs modeler verdict]` marker (still pending). No graded insert may appear as a settled, unsourced claim.

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

• This is the load-bearing change: the why-this-method narrative and the assumption-necessity / good-result judgments are graded reasoning. The AI must not originate them.
• Create methods/Qx/decisions/final-method-explainer_modeler_decision.md following the Human Decision Artifact Convention in CLAUDE.md, with:
• status: PENDING, decided_by: human (left for the human to confirm), decision_id: qx_method_explanation, decision_point: assumption_necessity.
• ai_suggestion: your best-effort draft — a suggested necessity label per assumption and a suggested result_good_threshold — each clearly marked [AI-DRAFT — needs modeler verdict]. This is YOUR view, in its own field; it is not the verdict.
• choice: left as a >> sentinel for the modeler to fill with, per assumption, necessity ∈ {necessary, simplifying} + a one-line why, and the committed result_good_threshold.
• The ## Modeler's rationale body left as a >> sentinel — human-authored, the AI must NOT write it.
• rejected_alternatives[*].reason: left as >> if not already settled in the decision log.
• evidence_refs: point at methods/Qx/qx_decision_log.md (the method_choice record) and planning/model_assumptions.md, so the human's rationale can cite a concrete token.
• Note the division of labor: the why-this-method narrative is NOT decided here — it was already decided at Gate G2.5 (method-selector) and lives as a method_choice record in the decision log; this skill only TRANSCRIBES it with provenance. This artifact's own PENDING decision is the assumption_necessity + result_good_threshold verdict.
• Then STOP and tell the modeler exactly what to fill in. Do NOT proceed to solution-package-builder or paper-section-writer. Gate G4.5 keeps the why-this-method narrative un-blessed until the 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 rationale field, its floor, and the copy/evidence checks are identical.

1. Hand off to the next skill — only after the decision artifact is DECIDED.

• First route the PENDING artifact to modeler-decision-logger so the human's assumption_necessity verdict folds into methods/Qx/qx_decision_log.md.
• If the final result analysis also exists: hand off to solution-package-builder.
• If the final result analysis does not yet exist: hand off to result-report-generator or workflow-orchestrator.

Outputs

Produce:

• methods/Qx/qx_final_method_explanation.md — the structural explanation (AI-drafted), with the why-this-method narrative TRANSCRIBED from the decision log (with ` provenance) and graded inserts either transcribed or marked [AI-DRAFT — needs modeler verdict]`.
• methods/Qx/decisions/final-method-explainer_modeler_decision.md — the PENDING decision artifact (decision_id: qx_method_explanation, decision_point: assumption_necessity), awaiting the human's per-assumption necessity labels + result_good_threshold. See Workflow step 9.

Output format

The document MUST contain all of the following sections:

# Qx Final Method Explanation

## 1. Method Selection Summary

- **Final selected method**: [method name]
- **Selection date / round**: [when this was decided]
- **Modeler**: [name or role if applicable]

### Candidate Methods Considered

| Method | Status | Reason (transcribed from decision log) |
|--------|--------|----------------------------------------|
| M1: [name] | Eliminated — Round N | [reason from `rejected_alternatives` — ``] |
| M2: [name] | Selected — Final | [the modeler's `method_choice` — ``] |
| M3: [name] | Eliminated — Round N | [reason from `rejected_alternatives` — ``] |

### Selection Justification (TRANSCRIBED — not authored here)

- **Why this method was chosen**: [verbatim/near-verbatim from the `method_choice` record's `modeler_rationale` — ``. Do NOT compose a new justification. If no such record exists, this subsection is BLOCKED, not filled.]
- **Trade-offs accepted**: [weaknesses or compromises, drawn from experiment reports + logged rationale]
- **Key differentiator**: [from the logged rationale / experiment evidence — not an AI-invented claim of superiority]

## 2. Model Assumptions

> Necessary-vs-simplifying labels are the human's verdict (decision artifact, `decision_point: assu

…

## 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.