Course Lab Final Staging

Course Lab Final Staging

Overview

Use this skill as the standalone late-stage non-figure writer for a lab report.

This package is independent and uses only local copied tools under /root/.codex/skills/course-lab-final-staging/. It should read the canonical main.tex plus stabilized upstream artifacts, then assemble a substantive draft that favors completeness over brevity: direct results for each case, handout-demanded indirect results, data-processing narration, uncertainty-calculation narration, modeling inclusion, synthesized discussion, calculation details appendix support, and appendix code support. The goal is a text-first draft that naturally supports a roughly 20-30 page two-column final PDF after course-lab-figure-evidence and final QC complete the later stages.

Standalone Tool Contract

Use Independently When

• A canonical report workspace already exists and needs late non-figure body assembly.
• Stable upstream artifacts already describe processed data, uncertainty support, interpretation, and discussion synthesis.
• The caller wants report-ready result/procedure/discussion prose and appendix staging without figure placement or compile/QC ownership.
• Optional confirmed references, modeling artifacts, calculation-detail manifests, symbolic-expressing handoffs, appendix data, or appendix code are available as explicit inputs.
• Front matter is already settled, theory-facing sections are already handled by course-lab-experiment-principle, and this late non-figure lane hands off to course-lab-figure-evidence and final QC after staging.

Minimum Inputs

• A canonical TeX entrypoint supplied through --main-tex.
• --body-scaffold-json identifying safe target sections, scaffold placeholders, and any summary-only rerun mode.
• --procedures-markdown, --processed-data-json, --results-interpretation-json, and --discussion-synthesis-json from stable upstream work.
• Output paths for final_staging_summary.json, final_staging_summary.md, final_staging_unresolved.md, and appendix_code_manifest.json.
• Safe TeX mutation authority: owned placeholder sections, explicitly draft-like blocks, or % course-lab-final-staging:allow-overwrite; otherwise preserve substantive prose and report the gap.

Optional Workflow Inputs

• --references-json containing confirmed staged literature context.
• --modeling-result, --appendix-data, --appendix-code, and --calculation-details-manifest when those artifacts should be rendered.
• Full symbolic helper handoff paths: --symbolic-handout, --symbolic-calculation-code, --symbolic-processed-result, --symbolic-result-key, and --symbolic-output-dir.
• Upstream comparison-case records for compact case-by-case comparison rendering and downstream paired-image placement.

Procedure

• Use /root/.codex/skills/course-lab-final-staging/scripts/build_final_staging.py and the local helper modules only.
• Validate every caller-provided artifact before mutating TeX; do not discover calculation details, appendix files, symbolic inputs, or literature sources by workspace scanning.
• Write only non-figure, late-stage body/appendix content into safe owned target sections.
• Preserve case-by-case direct and indirect results, uncertainty routes, and unresolved support limits.
• Treat symbolic expressing as an optional explicit handoff and inline its returned temporary TeX only when the path is safe and the selected result still needs mathematical procedure detail.

Outputs

• Mutated main.tex with late non-figure report assembly only where safe.
• final_staging_summary.json and final_staging_summary.md recording staged content, confirmed references, and normalized comparison cases.
• final_staging_unresolved.md recording missing artifacts, unsafe overwrite decisions, incomplete symbolic handoffs, or weak comparison support.
• appendix_code_manifest.json plus staged calculation-detail, data-record, and code appendix material when explicitly provided.

Validation

• Summary artifacts exist and list the major rendered lanes: direct results, indirect results, processing narration, uncertainty narration, discussion synthesis, and any explicit appendix/reference/modeling inputs.
• Unresolved output exists even when empty or informational, and preserves data-lack or support-limit notes instead of hiding them in confident prose.
• The TeX diff avoids front matter, theory-facing sections, late figure placement, compiler settings, and final-QC material.
• Local final-staging tests pass after documentation or helper changes.

Failure / Reroute Signals

• Missing required upstream artifacts: stop in standalone mode with the exact missing paths; in full-report mode, return reroute hints to the producing data, interpretation, discussion, or scaffold tool.
• Unsafe TeX targets or substantive user prose without an overwrite marker: preserve the block and record an unresolved staging issue.
• Incomplete symbolic handoff: continue without symbolic inlining when possible and record the missing fields in final_staging_unresolved.md.
• Malformed confirmed references, modeling results, appendix manifests, or comparison cases: skip that optional lane, preserve the rest of the staging run when safe, and emit a precise rerun hint.

Non-Ownership

• This tool does not transfer raw data, recompute results, recompute uncertainties, execute modeling, search for literature, place late figures, compile the report, or perform final QC.
• This tool does not infer or silently promote missing scientific scope from unrelated files.
• This tool does not own final report completeness after figures and QC; it hands off explicit artifacts for those later tools.

Optional Workflow Metadata

• Suggested future role label: writer.
• Typical upstream tools: course-lab-data-processing, course-lab-uncertainty-analysis, course-lab-results-interpretation, course-lab-discussion-synthesis.
• Typical downstream tools: course-lab-figure-evidence, course-lab-finalize-qc.

Workflow Notes

• Use local /root/.codex/skills/course-lab-final-staging/scripts/build_final_staging.py as the main entrypoint.
• Keep runtime dependencies local to /root/.codex/skills/course-lab-final-staging/.
• Mutate main.tex only in safe owned section bodies.
• Resolve target headings with explicit deterministic bucket matching across both \section{...} and \subsection{...} so synonyms such as Experimental Procedure and Observations, Results and Analysis, Local Discussion, and Code can be recognized without LLM-only fuzzy matching.
• In split reports, prefer same-block subsection targets such as Local Discussion inside the active experiment block before falling back to later global sections such as Discussion.
• Allow overwrite of explicit draft-like scaffold prose when it is still short, clearly provisional, and does not already look like substantive authored report content.
• Accept % course-lab-final-staging:allow-overwrite as an intentional handoff marker when upstream skills or manual editors want final staging to replace a local draft block on the next run.
• Honor body_scaffold.json field staging_mode: "summary_only_existing_draft" for reruns on already-authored drafts: preserve substantive target sections instead of failing, but still update any safe placeholder-owned sections and still emit the staging summary artifacts.
• Preserve case-by-case direct results instead of flattening them into one short summary.
• When upstream artifacts expose multiple validated comparison_cases, preserve them as multiple report blocks instead of collapsing them into one aggregate comparison paragraph.
• When many validated comparison_cases are present, prefer a compact comparison matrix or similarly dense rendering over one long per-case paragraph stack so the later figure stage still has room.
• Include handout-demanded indirect results when upstream artifacts support them.
• Write report-side narration for the data-processing procedure and the corresponding uncertainty-calculation procedure from upstream artifacts.
• When upstream uncertainty artifacts expose result-specific formulas, render the explicit partial derivative propagation formula for each reported indirect result instead of only a generic definition.
• After those formulas, write the substituted key quantities and evaluated steps that lead to the reported uncertainty, including direct-summary terms such as s, u_a, u_b, u_c, and the final expanded uncertainty when those artifacts exist.
• Prefer compact tables for those middle uncertainty results when several quantities must be shown together, especially in two-column report layouts.
• Format detailed propagation equations so they can wrap cleanly inside a two-column page, using multi-line math instead of one unbroken inline expression.
• When an indirect result still lacks enough undergraduate-readable mathematical procedure after the staged processing and uncertainty artifacts are rendered, use the optional helper course-lab-symbolic-expressing more eagerly if the caller has explicitly provided a symbolic handout, symbolic calculation code, symbolic processed result, symbolic result key, and symbolic output dir.
• Invoke /root/.codex/skills/course-lab-symbolic-expressing/scripts/render_symbolic_explanation.py only from those explicit handoffs, consume the returned tex_path where it is safely inside the symbolic output dir, and inline the returned temporary TeX content only inside final-staging-owned result/procedure sections.
• Treat course-lab-symbolic-expressing as an optional helper, not a required stage: if the symbolic handoff is incomplete or the helper cannot trace the selected result, keep the gap visible in final_staging_unresolved.md instead of recomputing results or scanning the workspace.
• Include modeling results when modeling artifacts exist.
• Accept confirmed references through --references-json and render only the staged literature_report entries that upstream leaves already confirmed.
• Preserve confirmed references in the staging summary outputs so later report or figure steps can reuse the same downstream-only literature context.
• Convert synthesized discussion artifacts into final report prose without hiding unresolved support limits.
• Attach explicit calculation details in the appendix when course-lab-data-processing provides a --calculation-details-manifest handoff.
• Place Calculation Details before Code in appendix rendering when both are present.
• Render that Calculation Details appendix as full-width appendix material when needed; it does not need to preserve the two-column body-layout math constraints used elsewhere in the report.
• Attach major code in the appendix when those files are explicitly provided.
• Attach uncited data attachments in the appendix when those files are explicitly provided through --appendix-data, using a visually distinct data-record block instead of the code-style block.
• Require the caller to pass appendix code paths explicitly through --appendix-code when discovered simulation or modeling scripts should appear in the report appendix.
• Require the caller to pass appendix data-file paths explicitly through --appendix-data when staged data bundles should appear in the report appendix.
• Require the caller to pass the calculation-details manifest explicitly through --calculation-details-manifest; this skill does not discover calculation-detail attachments by scanning the workspace.
• Require symbolic handoff paths explicitly through --symbolic-handout, --symbolic-calculation-code, --symbolic-processed-result, --symbolic-result-key, and --symbolic-output-dir when the optional helper is desired; this skill does not discover those handoff files by scanning the workspace.
• Require the caller to pass confirmed references explicitly through --references-json; this skill does not discover literature sources from search specs, raw URLs, or workspace scans.
• Render explicitly provided appendix code as selectable report text when the downstream build path supports it, using compact styled code blocks rather than path-only placeholders.
• Skip appendix data files that are already cited by filename in the current report draft, so the appendix only catches still-unmentioned staged data attachments.
• Emit:
  • final_staging_summary.json
  • final_staging_summary.md
  • final_staging_unresolved.md
  • appendix_code_manifest.json
• Include filtered confirmed literature references in final_staging_summary.json when --references-json is provided, but do not invent new comparison sources at this stage.
• Include normalized comparison_cases in final_staging_summary.json when case-paired observed/simulation assets were discovered, so course-lab-figure-evidence can place same-case experiment-vs-simulation figures instead of rediscovering those pairings.

Primary Command

python3 /root/.codex/skills/course-lab-final-staging/scripts/build_final_staging.py \
  --main-tex "/path/to/results/<experiment>/main.tex" \
  --body-scaffold-json "/path/to/results/<experiment>/body_scaffold.json" \
  --procedures-markdown "/path/to/results/<experiment>/<experiment-safe-name>_procedures.md" \
  --processed-data-json "/path/to/results/<experiment>/analysis/processed_data.json" \
  --calculation-details-manifest "/path/to/results/<experiment>/analysis/calculation_details_manifest.json" \
  --symbolic-handout "/path/to/results/<experiment>/decoded_handout.md" \
  --symbolic-calculation-code "/path/to/results/<experiment>/analysis/process_data.py" \
  --symbolic-processed-result "/path/to/results/<experiment>/analysis/derived_uncertainty.json" \
  --symbolic-result-key "wave_speed" \
  --symbolic-output-dir "/path/to/results/<experiment>/analysis/symbolic_expressing/tmp" \
  --results-interpretation-json "/path/to/results/<experiment>/results_interpretation.json" \
  --discussion-synthesis-json "/path/to/results/<experiment>/discussion_synthesis.json" \
  --references-json "/path/to/results/<experiment>/analysis/reference_values.json" \
  --modeling-result "/path/to/results/<experiment>/modeling/batch_run_result.json" \
  --appendix-data "/path/to/results/<experiment>/analysis/appendix_data/case1_measurements.txt" \
  --appendix-data "/path/to/results/<experiment>/analysis/appendix_data/case2_measurements.txt" \
  --appendix-code "/path/to/results/<experiment>/modeling/model.wl" \
  --appendix-code "/path/to/results/<experiment>/analysis/process_data.py" \
  --output-summary-json "/path/to/results/<experiment>/final_staging_summary.json" \
  --output-summary-markdown "/path/to/results/<experiment>/final_staging_summary.md" \
  --output-unresolved "/path/to/results/<experiment>/final_staging_unresolved.md" \
  --output-appendix-manifest "/path/to/results/<experiment>/appendix_code_manifest.json"

Workflow

1. Confirm that main.tex and the required upstream artifacts already exist.
2. Read references/shared_draft_contract.md before mutating the draft.
3. Collect and validate the staging inputs with the local helper scripts.
4. Write report-ready narration for the data-processing procedure.
5. Write report-ready narration for the corresponding uncertainty-calculation procedure.
6. Render direct results and indirect results per case so former results remain visible instead of compressed away.
7. For each indirect result with staged uncertainty support, show the specialized partial derivative propagation formula and the substituted values that evaluate it, preferring tables for grouped middle values and line-breakable math for two-column drafts.
8. If selected indirect results still lack adequate mathematical procedure detail and the caller supplied the full symbolic handoff, call course-lab-symbolic-expressing with the explicit handout, calculation-code, processed-result, result-key, and output paths; consume the returned tex_path only when safe.
9. Render one comparison block per validated comparison case when paired evidence or explicit comparison_cases records exist, but switch to a compact matrix-style rendering when many cases would otherwise consume too much body space.
10. Render confirmed literature-backed comparison context only when --references-json provides staged literature_report entries; do not search for literature or infer missing citations here.
11. Insert interpretation bridges, modeling results, and synthesized discussion where the artifact evidence supports them.
12. If some comparison-case material cannot be mapped safely, keep that gap visible in unresolved outputs instead of silently shortening the report.
13. Stage explicit calculation details as appendix attachments before data files and code when the caller provides a calculation-details manifest.
14. Stage appendix data-record references and distinct colored data listings when --appendix-data files are provided and the current draft does not already cite them by filename.
15. Stage appendix code references and compact styled code listings when major code files are provided.
16. Treat calculation details, appendix data files, appendix code, confirmed references, and symbolic-expressing inputs as explicit caller-owned handoffs: this skill does not discover those attachments from workspace scans, discovery manifests, result folders, or late search logic on its own.
17. Emit staging summaries and unresolved-gap notes.
18. Stop and hand off to course-lab-figure-evidence, then final QC.

Boundary Rules

• This skill is a late-stage non-figure writer.
• This skill does not overwrite front matter or theory-facing sections already owned upstream.
• This skill does not recompute results, recompute uncertainties, or execute modeling.
• This skill does not place late figures.
• This skill owns case-by-case comparison prose; course-lab-figure-evidence owns later paired-image placement.
• This skill may compact comparison prose or tables to protect page budget, but it still does not own late figure layout.
• This skill does not compile the report.
• This skill does not choose or refresh the TeX compiler; final build-path ownership stays with final QC.
• This skill does not take over final QC.
• course-lab-symbolic-expressing is not a required stage and does not mutate main.tex; final-staging remains the report mutation owner and may only inline returned temporary TeX inside its owned section bodies.
• This skill does not discover calculation details files from discovery artifacts or result directories; callers must pass that manifest explicitly.
• This skill does not discover appendix data files from discovery artifacts or result directories; callers must pass those data-file paths explicitly.
• This skill does not discover appendix code files from discovery artifacts or result directories; callers must pass those paths explicitly.
• This skill does not discover symbolic handout, calculation-code, processed-result, result-key, or output-dir inputs; callers must pass those paths and keys explicitly when symbolic support is desired.
• This skill does not discover literature at late stage; confirmed references must arrive through --references-json.
• This skill should fail clearly instead of overwriting substantive user prose in an owned section unless the block is explicitly draft-like or intentionally handed over with % course-lab-final-staging:allow-overwrite.
• When staging_mode: "summary_only_existing_draft" is explicitly set in body_scaffold.json, preserving substantive user prose and emitting a summary-only rerun is the intended behavior rather than a failure.
• Keep all runtime tool usage local to this standalone folder.

Common Mistakes

• Flattening several experiment cases into one short result paragraph.
• Flattening multiple validated comparison cases into one short aggregate comparison paragraph.
• Letting many comparison cases expand into a long stack of near-duplicate paragraph blocks when a compact comparison matrix would preserve more space for later evidence.
• Listing only final indirect values without showing the data-processing route or uncertainty route.
• Stopping at a generic propagation definition when the staged artifacts are rich enough to show the specific partial derivative formula and substituted values for that indirect result.
• Ignoring a complete symbolic-expressing handoff when an indirect result still lacks undergraduate-readable mathematical procedure detail.
• Treating symbolic-expressing as mandatory, allowing it to recompute results, or letting it mutate main.tex directly instead of returning a tex_path for final-staging to consume.
• Leaving uncertainty middle results in paragraph-long prose when a compact table would keep the two-column report readable.
• Emitting one unbroken propagation expression that overflows the column instead of using multi-line math that can wrap.
• Leaving modeling outputs detached from the report when modeling artifacts already exist.
• Hiding calculation details in body prose or hand-maintained special includes after course-lab-data-processing already provided appendix-ready attachments.
• Forgetting that uncited data bundles can belong in a separate appendix data-record lane instead of being buried in code or omitted entirely.
• Trimming appendix code support too early even though reproducibility material should remain visible.
• Reaching back into parent or sibling skill folders instead of using this local package.
• Drifting into course-lab-figure-evidence or final QC responsibilities.

Resources

• scripts/common.py: local helper functions for JSON, TeX section ownership, and safe-overwrite rules
• scripts/collect_staging_inputs.py: local input collector and validator
• scripts/render_results_sections.py: local renderer for data-processing narration, uncertainty narration, and per-case results
• scripts/render_appendix_materials.py: local appendix and code-manifest renderer
• scripts/render_catalog_and_timing.py: local catalogue and timing summary renderer
• scripts/build_final_staging.py: local final-staging builder
• references/report_structure.md: local report-depth and structure guidance
• references/shared_draft_contract.md: local safe-mutation guidance for reruns and owned regions