Course Lab Results Interpretation

Course Lab Results Interpretation

Overview

Turn handout-grounded lab evidence into standalone interpretation artifacts without drifting into discussion generation, direct report mutation, or final QC.

This skill is standalone with local copied tools. It should read the normalized handout first, then justify processed-data artifacts through explicit comparison lanes against simulation outputs, handout standard/example values, internet references, and theory-based comparison values when those exist, while keeping unresolved comparison gaps visible instead of hiding them inside stronger prose.

Standalone Tool Contract

Use Independently When

• Normalized handout artifacts and processed-data artifacts exist and the task is to produce artifact-only result interpretation, not report mutation.
• The run needs handout-first justification, comparison lanes, anomaly visibility, completeness checks, or proposal artifacts before discussion or final staging.

Minimum Inputs

• Normalized handout JSON/Markdown artifacts.
• Processed-data JSON/Markdown artifacts or result inventory produced from validated data.
• Output destination for interpretation JSON/Markdown artifacts.

Optional Workflow Inputs

• Plot manifests, modeling outputs, simulation outputs, reference/literature artifacts, run-plan comparison obligations, and approved proposal metadata.
• Theoretical comparison values or upstream theory artifacts when explicitly available.
• Existing agent_proposed_key_results state for pending/approved/rejected proposal tracking.

Procedure

• Read the handout before interpreting processed results and build explicit comparison lanes only from available support.
• Emit support/credibility labels such as handout-backed, data-backed, plot-backed, simulation-backed, reference-backed, theory-backed, generic/speculative, or unresolved.
• Keep agent_proposed_key_results and candidate_literature_sources artifact-only and pending_user until a user marks them approved, rejected, or needs_revision.
• Preserve unresolved comparison gaps instead of downgrading or hiding them in stronger prose.

Outputs

• Artifact-only interpretation JSON and Markdown.
• comparison_records across supported handout expectations, simulation outputs, handout standards, internet/reference values, theory values, and approved literature values.
• agent_proposed_key_results, candidate_literature_sources, completeness warnings, and unresolved justification gaps where applicable.

Validation

• Every confirmed comparison record has an explicit support source and credibility/support label.
• Pending proposals are not promoted into confirmed comparison sets or canonical references.
• Missing modeling/reference/theory support remains visible in unresolved output while still allowing honest partial interpretation artifacts.

Failure / Reroute Signals

• Missing processed data or normalized handout: in standalone mode, stop and request the artifact; in full-workflow mode, reroute to the missing upstream tool.
• Missing optional reference/model lane: emit partial interpretation plus unresolved gap rather than blocking all output unless that lane is required by the handout.
• Extra comparison-worthy result discovered: emit it as pending_user proposal, not final scope.

Non-Ownership

• Does not mutate main.tex, draft broad final discussion prose, stage figures, or run final QC.
• Does not silently confirm internet/theory/simulation comparisons without source support.

Optional Workflow Metadata

• Suggested future role label: data-analyst.
• Typical upstream tools: course-lab-data-processing, course-lab-uncertainty-analysis, course-lab-plotting, modeling/reference tools.
• Typical downstream tools: course-lab-discussion-ideas, course-lab-discussion-synthesis, course-lab-final-staging.

Primary Command

python3 /root/.codex/skills/course-lab-results-interpretation/scripts/build_results_interpretation.py \
  --handout-sections-markdown "/path/to/results/<experiment>/notes/sections.md" \
  --handout-sections-json "/path/to/results/<experiment>/notes/sections.json" \
  --processed-data-json "/path/to/results/<experiment>/analysis/processed_data.json" \
  --processed-data-markdown "/path/to/results/<experiment>/analysis/processed_data.md" \
  --plots-manifest "/path/to/plottings/plot_manifest.json" \
  --modeling-result "/path/to/modeling/run_result.json" \
  --references-json "/path/to/results/<experiment>/analysis/reference_values.json" \
  --run-plan-json "/path/to/results/<experiment>/<experiment-safe-name>_run_plan.json" \
  --run-plan "/path/to/results/<experiment>/<experiment-safe-name>_run_plan.md" \
  --output-json "/path/to/results/<experiment>/results_interpretation.json" \
  --output-markdown "/path/to/results/<experiment>/results_interpretation.md" \
  --output-unresolved "/path/to/results/<experiment>/results_interpretation_unresolved.md"

Reference staging helper before the interpretation pass:

python3 /root/.codex/skills/course-lab-results-interpretation/scripts/stage_reference_values.py \
  --handout-sections-markdown "/path/to/results/<experiment>/notes/sections.md" \
  --handout-sections-json "/path/to/results/<experiment>/notes/sections.json" \
  --processed-data-json "/path/to/results/<experiment>/analysis/processed_data.json" \
  --seed-references-json "/path/to/results/<experiment>/analysis/reference_seed_values.json" \
  --search-spec-json "/path/to/results/<experiment>/analysis/reference_search_spec.json" \
  --approved-literature-json "/path/to/results/<experiment>/analysis/approved_literature.json" \
  --output-json "/path/to/results/<experiment>/analysis/reference_values.json" \
  --output-unresolved "/path/to/results/<experiment>/analysis/reference_values_unresolved.md"

Recommended references-json shape when justification needs multiple lanes:

{
  "comparison_requirements": {
    "required_bases": ["internet_reference", "theoretical_computation"],
    "optional_bases": ["handout_standard"]
  },
  "references": [
    {
      "name": "youngs_modulus",
      "label": "Handout stainless reference",
      "value": 1.95e11,
      "unit": "Pa",
      "comparison_basis": "handout_standard",
      "source": "notes/sections.md:157"
    },
    {
      "name": "youngs_modulus",
      "label": "Published alloy reference",
      "value": 2.00e11,
      "unit": "Pa",
      "comparison_basis": "internet_reference",
      "source": "https://example.org/material-data"
    },
    {
      "name": "youngs_modulus",
      "label": "Beam-model inversion",
      "value": 2.01e11,
      "unit": "Pa",
      "comparison_basis": "theoretical_computation",
      "source": "analysis/theory_checks.json:youngs_modulus"
    }
  ]
}

Workflow

1. Confirm that processed-data artifacts already exist.
2. Read the normalized handout first.
3. Read optional handout JSON only when handout Markdown is absent.
4. Read processed-data JSON as the primary data evidence base.
5. Read optional processed-data Markdown only as a consistency check against the JSON artifact.
6. Gather justification evidence for the processed results that need checking.
7. Prefer running /root/.codex/skills/course-lab-results-interpretation/scripts/stage_reference_values.py before the interpretation pass when internet-reference staging is needed.
8. Read optional plot manifests, modeling outputs, references, run-plan expectations, and confirmed run-plan JSON obligations when they exist.
9. For each important processed result, compare against:
   • handout standard/example values when the handout provides them
   • internet references gathered from credible sources with preserved links
   • relevant theoretical comparison values or upstream theory artifacts
10. When comparison_obligations are confirmed upstream, use them to drive primary lanes such as theory_vs_data, simulation_vs_data, and literature_report_vs_data.
11. Build a result inventory before writing interpretation notes.
12. Build explicit comparison_records across handout expectations, simulation outputs, handout standards, internet references, theory values, and approved literature values when those lanes are supported.
13. Emit agent_proposed_key_results and candidate_literature_sources for extra results that still need confirmation; keep those proposals artifact-only and pending until the user marks them approved, rejected, or needs_revision.
14. Emit artifact-only JSON and Markdown outputs for downstream consumers.
15. Keep unresolved notes explicit when simulation or justification lanes are missing, evidence conflicts, or expected result families are still absent.

Quick Reference

Contract Notes

• Use local /root/.codex/skills/course-lab-results-interpretation/scripts/build_results_interpretation.py as the main synthesis entrypoint.
• Use local /root/.codex/skills/course-lab-results-interpretation/scripts/stage_reference_values.py to stage reference_values.json by merging local handout/theory seeds with live internet search results.
• Keep runtime dependencies local to /root/.codex/skills/course-lab-results-interpretation/.
• Read the normalized handout first and treat it as required interpretation context.
• Treat processed-data JSON as a required base input.
• Prefer normalized handout Markdown first. Fall back to normalized handout JSON only when Markdown is absent.
• Treat processed-data Markdown, plot manifests, modeling outputs, references, run-plan expectations, and confirmed comparison_obligations as optional supporting inputs.
• Emit artifact-only outputs:
  • results_interpretation.json
  • results_interpretation.md
  • results_interpretation_unresolved.md
• Include comparison_records in results_interpretation.json so handout/data/simulation/theory comparisons stay explicit instead of getting buried in prose.
• When a confirmed run-plan JSON exists, read comparison_obligations from it and treat those obligations as the primary comparison contract.
• Emit agent_proposed_key_results when interpretation discovers extra comparison-worthy results that still need user confirmation.
• Mark proposals explicitly with states such as pending_user, and keep only later approved proposals eligible for promotion into downstream reference artifacts.
• Emit candidate_literature_sources only for proposal paths; do not silently promote those sources into the confirmed comparison set.
• Prefer one reference artifact that can hold multiple entries per processed result, distinguished by comparison_basis such as handout_standard, internet_reference, and theoretical_computation.
• Preserve approved literature promotion with explicit comparison_basis: literature_report and lane: literature_report_vs_data.
• When internet references are used, preserve the concrete source link and enough citation metadata for later attribution.
• Use comparison_requirements in references-json when a run should explicitly require some justification lanes, for example internet_reference and theoretical_computation.
• If theory or reference support is missing, still emit partial interpretation artifacts when the remaining lanes stay honest.
• If a required justification lane is missing for a processed result, keep that gap explicit in unresolved output instead of silently downgrading the check.
• If the handout expects simulation comparison and modeling artifacts are missing, keep that gap visible in unresolved output instead of downgrading it silently.
• Keep unresolved comparison gaps, conflicting evidence, and missing expected result families visible instead of inventing stronger conclusions.

Boundary Rules

• This skill starts only after normalized handout artifacts and processed-data artifacts are available.
• This skill owns artifact-only interpretation outputs, not report mutation.
• This skill does not run modeling, generate discussion ideas, or perform final QC.
• This skill does not rerun upstream raw-data processing or full modeling jobs, but it may compute lightweight comparison deltas once the comparison values already exist.
• Keep all runtime tool usage local to this standalone folder.
• Do not mutate main.tex or any direct report file from this skill.
• Do not write handout, internet, theory, or simulation comparisons as confirmed when the supporting values are missing.
• Do not silently move pending_user proposal items into the confirmed comparison set.
• Do not promote candidate literature sources unless the parent flow has marked them approved.
• Do not skip the handout. Read the normalized handout first.

Common Mistakes

• Reaching back into the parent skill or sibling skill folders instead of using the local copied script.
• Interpreting processed data before reading the handout.
• Turning missing handout/internet/theory lanes into implicit agreement language.
• Treating simulation outputs as decorative source hints instead of explicit comparison targets.
• Collapsing handout standards, internet references, and theory calculations into one vague comparison bucket.
• Folding discussion generation into the interpretation layer.
• Treating processed-data Markdown as a silent override instead of a consistency check.
• Letting the skill mutate report files instead of staying artifact-only.

Resources

• scripts/common.py: local helpers for JSON and text I/O
• scripts/build_results_interpretation.py: local interpretation builder
• scripts/stage_reference_values.py: local helper that searches the web and stages reference_values.json
• tests/baseline_failures.md: RED-phase failure record for this skill
• tests/test_skill_package.py: standalone package checks
• tests/test_build_results_interpretation.py: CLI behavior checks
• tests/test_stage_reference_values.py: staged reference helper checks