---
name: osteoboard
description: Run the frozen local Osteosarc-derived demo bundle to validate inputs, reconstruct denominator-aware recurrent-specimen shifts, and produce restrained osteosarcoma target-triage outputs. Use when asked to run or verify OsteoBoard.
allowed-tools: Bash(./run_skill.sh), Bash(./research_note/build_note.sh), Bash(python *), Bash(python3 *), Bash(pip *), Bash(ls *), Bash(shasum *), Bash(test *)
requires_python: "3.9+"
package_manager: pip
repo_root: .
canonical_output_dir: results
---

# OsteoBoard

OsteoBoard is a frozen, deterministic, local skill that validates a bundled Osteosarc-derived demo case, reconstructs denominator-aware longitudinal state shifts across clinically distinct recurrent specimens, applies rule-conditioned target triage over a frozen five-target panel, and emits a restrained report plus verification outputs.

> OsteoBoard reconstructs descriptive, hypothesis-generating longitudinal state shifts and target-triage decisions in a public N-of-1 recurrent osteosarcoma case using a frozen local bundle; it does not estimate single-treatment causal effects and should not be used as medical advice.

## Scope And Non-Scope

This skill will:

- validate the frozen bundle under `data/demo_bundle/` against bundled schemas and SHA256 hashes
- summarize longitudinal stromal versus immune shifts from the bundled `T1` to `T3` tumor scRNA tables
- report both `t_cell_fraction_of_all_cells` and `t_cell_share_of_immune`
- rank `FAP`, `CD276`, `MDM2`, `PANX3`, and `EPHA2` using local evidence plus ordered caveat rules
- generate a tumor-board style report, three figures, and a verification JSON

This skill will not:

- download or reprocess the raw public Osteosarc archive
- use PBMC, vaccine, BAM, FASTQ, or RDS assets at runtime
- make causal claims, efficacy claims, or clinical recommendations
- require credentials, private buckets, or manual reconstruction steps
- depend on absolute paths, home-directory state, preexisting outputs, or network access after dependency installation

## Prerequisites

- `python3` 3.9 or newer
- Python packages from `requirements.txt`
- local filesystem access to this repository

Install dependencies once:

```bash
python3 -m pip install -r requirements.txt
```

After dependencies are installed, the canonical skill run requires no network access.

## Canonical Entry Point

Run from the repository root:

```bash
./run_skill.sh
```

Use only `./run_skill.sh` for review. Direct invocation of individual scripts is optional and non-canonical.

## Expected Runtime

On a typical laptop-class CPU, the bundled run should complete in well under a minute and usually in a few seconds. The runtime is driven entirely by local TSV, YAML, Markdown, JSON, and PNG generation over the frozen bundle.

## Required Outputs

A successful canonical run produces:

- `results/00_bundle_validation.txt`
- `results/01_longitudinal_summary.tsv`
- `results/02_program_shift_summary.tsv`
- `results/03_target_ranking.tsv`
- `results/04_multimodal_board_report.md`
- `results/05_verification.json`
- `results/figures/figure1_workflow_overview.png`
- `results/figures/figure2_longitudinal_shift.png`
- `results/figures/figure3_target_triage.png`

## Verification Command

The canonical runner already executes verification, but the verifier can also be invoked directly:

```bash
python3 scripts/05_verify_outputs.py
```

A separate clean-directory audit artifact at `results/final_cold_start_audit.txt` is informative but is not part of the required output contract.

Optional research-note build:

```bash
./research_note/build_note.sh
```

The LaTeX note is optional and is not a dependency of `./run_skill.sh`.

## Interpretation Guardrails

- This is a deterministic longitudinal tumor-board style reconstruction over a frozen processed bundle, not a raw-data processing pipeline.
- The public specimen convention is preserved: `T0` resection, `T1` re-resection, `T2` biopsy, `T3` resection.
- Headline `T3` longitudinal fractions come from the canonical non-enriched tumor object; `T3_CD45neg` is excluded from headline fractions unless analyzed separately as sensitivity material.
- Imaging is orthogonal support only. It is not the longitudinal proof layer for the `T1` to `T3` claim.
- `overall_priority_score` is within-candidate-panel ordinal only. Raw score alone does not determine final biology because ordered caveat rules can condition or veto a target.
- The output table is for hypothesis triage, not treatment recommendation.
- The imaging-aware veto is property-based rather than target-name hard-coded: strong target signal can still be demoted when local imaging or dependency evidence introduces a safety or interpretability caveat.

## Known Limitations

- single public N-of-1 case built from clinically distinct recurrent specimens rather than serial samples of one unchanged lesion
- descriptive and hypothesis-generating rather than causal
- bundled candidate panel only; no claim of global target completeness
- MDM2 remains conditional because TP53 functional context is unknown in the frozen bundle

## Citation And Provenance

- The bundle freezes facts derived from the public Osteosarc site and related public data assets recorded in `data/demo_bundle/metadata.yaml`.
- The scientific note is in `research_note/note.tex` with bibliography in `research_note/refs.bib`.
- The broader source memo is in `SOURCES.md`.
- The authorship line in the research note includes `Claw` as corresponding co-author to match the venue rule.

## Additional Resources

- For repository layout and output expectations, see `README.md`.
- For frozen bundle contents and provenance, see `data/demo_bundle/README.md`.
- For optional note build details, see `research_note/NOTE_BUILDING.md`.