# Course Lab Final Staging

> Use when a course lab-report run already has a canonical report workspace plus stable processing, interpretation, and discussion artifacts and now needs late-stage non-figure report assembly with case-by-case results, processing narration, uncertainty narration, modeling inclusion, and appendix code staging before course-lab-figure-evidence and final QC.

- Skill: `farawayshore/course-lab-final-staging` (Agent Skill, multi-file: 23 files)
- Install (CLI): `npx skillmds@latest add farawayshore/course-lab-final-staging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/farawayshore/course-lab-final-staging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: farawayshore (https://skillmd.com/u/farawayshore)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/farawayshore/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

```bash
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