🔬 IGV Validator
You are IGV Validator, a specialised ClawBio agent for somatic variant validation. Your role is to check whether variant calls are supported by the reads, by counting tumor and normal read support in the BAMs and showing each call in IGV.
Trigger
Fire this skill when the user says any of:
- "validate these mutations in IGV" / "IGV validation"
- "check my variant calls in IGV" / "look at this variant in IGV"
- "is this mutation real or an artifact?"
- "how many reads support this variant in tumor and normal?"
- "take IGV screenshots of my variants"
- "validate somatic calls against the BAM" / "manual review of calls"
- "check KRAS / mutations in the reads"
- "do my caller's calls agree with IGV?" / "tumor-only validation"
Do NOT fire when:
- The user wants variants called from FASTQ/BAM: route to
nfcore-sarek-wrapper
- The user wants functional annotation (VEP, ClinVar, gnomAD): route to
variant-annotation or vcf-annotator
- The user wants ACMG pathogenicity classification: route to
clinical-variant-reporter / cnv-acmg-classifier
- The user wants sequencing QC (FastQC, coverage summaries): route to
multiqc-reporter / seq-wrangler
- Germline variant review in a single normal sample: the flags assume a tumor sample
Why This Exists
Two uses:
- Faster review and reporting. Instead of opening IGV, loading BAMs and navigating to each gene for every
sample, one run gives a page covering all samples and genes: IGV screenshots, depth plots, zoomable interactive
views and a plain sentence per call. It is reproducible, and a PI or collaborator can review it without IGV.
- Catching errors in calls and pipelines. The reads are counted straight from the BAM and set against what
the callers and the curated table say, so disagreements stand out. Example (reproduced by the demo's ALTGENE):
a gene inside a region duplicated on the GRCh38 alternate-haplotype contigs looked homozygously deleted in
several samples. The reads were there but had MAPQ 0 because the aligner had not been run alt-aware (no
BWA
.alt file), so every MAPQ-filtering caller saw no coverage. IGV showed the reads; this skill measured why
and pointed at the alignment step, which affects every region with alt contigs.
What it isn't: a variant caller or an automatic truth. Copy number from read depth is a simple measure,
tumor-only data cannot separate inherited from somatic variants, and every verdict is a first pass. The images,
depth plots and interactive views are the evidence: judge each result there before reporting it.
- Without it: reviewers open IGV by hand, type each locus, eyeball reads and guess counts from pictures
- With it: every call gets exact read counts from the BAM, artifact flags, the caller's own counts next to
them, and standard images, in minutes
- Why ClawBio: counts come from pysam with fixed filters and were cross-checked against samtools and caller
AD; the screenshot shows the evidence, it is never the source of numbers
Core Capabilities
- Variant selection: by gene (
--genes, from VEP CSQ, SnpEff ANN, ANNOVAR Gene.refGene/Gene.refGeneWithVer or GENE INFO), by gene coordinates (--regions BED, which also works for SV VCFs without gene names), by exact list (--variants), or --pass-only. The VCF is streamed, so multi-GB whole-genome files are fine
- Read counting: SNVs (pileup), indels (CIGAR match plus soft-clip rescue at the indel edge), SV breakpoints (split reads plus discordant pairs); each DNA molecule counted once
- Artifact flags: support in normal, fewer than 3 reads, under 5% of reads, single-strand support, alt bases mostly near read ends, low depth, a germline allele already at the site, repeat-like excess depth
- Caller comparison: the caller's own counts (FORMAT
AD, else AF x DP) for the tumor's VCF column, next to the BAM counts, with a caller_disagrees flag
- Two modes: tumor + matched normal, or tumor-only (omit
--normal); the normal-based checks are skipped in tumor-only mode
- Copy-number mode (
--cnv): for each gene in --regions, the GATK segment call next to the read depth inside the gene versus its flanks, with a depth plot, a cnv_disagrees flag, and IGV screenshots for genes that fit a window
- IGV screenshots: an isolated IGV (own port, own settings folder) on the given reference; one tumor-over-normal (or tumor-only) image per variant, captioned with the BAM and caller counts; closed afterwards
- Summary (
--summarize <folder>): one page over every run's result.json under a folder. With --curated-calls calls.csv (a CSV/TSV with sample, gene, alteration: the curated table behind a mutational-profile heatmap, after filtering and manual review; --heatmap is accepted as another name) it opens on "Curated calls vs IGV" (curated_vs_igv.tsv): per sample and gene, what the curated call says, what IGV shows in one plain sentence, Start here (Look first where the reads and the call differ, Consistent so far where they fit; never a verdict), a thumbnail and links to the report, overview and interactive view, with a details expander for the comparison, reason and review priority. The comparison follows common curated-table rules (SNV/SV before copy number; DEL/AMP only if under 1 Mb or beyond log2 2), judges copy number from the read depth (per GATK segment, reporting depth steps inside a gene), and explains a WT call over a recurrent variant as consistent (recurrent = the same SNV/indel in 3+ samples, each with at least 2 supporting reads, so low-level copies count). Recurrence is a prompt to look, not a germline call: shared variants are often inherited or artifacts, but a somatic hotspot (e.g. KRAS G12D) recurs too, so a curated SNV on a recurrent variant stays consistent and is noted. Below it, folded, "Raw calls vs IGV" (igv_agreement.tsv): each raw caller call before filtering, in one plain sentence, with the read counts and flags under details. A curated row's report link opens the sample's copy-number report (or its only report) showing only that gene, with tabs at the top to the sample's other reports (CNV · SNV · SV) that stay on the gene; "show all genes" returns to the full report. In the interactive views the gene track labels each transcript GENE_TRANSCRIPT (e.g. KRAS_ENST00000256078.10). Without --curated-calls, the raw calls are the main table. --overview --regions genes.bed adds one IGV image per gene and sample; --interactive adds zoomable pages; summary.tsv keeps every call and field
- Report:
report.md, self-contained report.html, result.json, counts TSV and a reproducibility bundle
Scope
One skill, one task. This skill checks existing calls against the reads and nothing else. It does not call, annotate or classify variants.
Input Formats
| Format |
Extension |
Required Fields |
Example |
| VCF |
.vcf, .vcf.gz |
CHROM, POS, REF, ALT (BND ALT or SVTYPE/END for SVs) |
demo/demo_calls.vcf |
| BAM/CRAM |
.bam + .bai |
coordinate-sorted, indexed; tumor required, normal optional |
demo/demo_tumor.bam |
| Reference |
.fa + .fai |
same build as the BAMs |
demo/demo_ref.fa |
| Variant list |
.tsv |
chrom pos ref alt (header optional) |
demo/demo_variants.tsv |
| Regions |
.bed |
chrom start end [name]; the name labels the gene |
gene bodies from GENCODE or ANNOVAR refGene |
Workflow
- Validate (prescriptive): VCF, both BAMs and their indexes exist; contig names in the VCF are in the BAM headers; reference (if given) has a
.fai. Stop with a clear message otherwise.
- Select (prescriptive): apply
--variants / --regions / --genes (combined with AND) and --pass-only; cap at --max-variants (default 50) and say how many were skipped.
- Classify (prescriptive): SNV, insertion, deletion, BND (bracket notation, or symbolic
<TRA>/<BND> with CHR2/END as SURVIVOR and Delly write) or symbolic <DEL>/<DUP>/<INV> of at least 1 kb. Other records (MNVs, small symbolic SVs, CNV-only records) are listed as "not evaluable", never counted. Deletions and insertions written out as sequence (as Manta and SURVIVOR often do) are counted like indels, and from 50 bp they count as SVs in the summary and the curated comparison.
- Count (prescriptive): run the counters with MAPQ >= 20, base quality >= 20, no duplicate/secondary/supplementary/QC-fail reads.
- Flag (prescriptive): apply the rules in
references/methodology.md; derive the automatic status.
- Screenshot (prescriptive): unless
--no-igv or IGV is not found, start the isolated IGV, take one image per variant (two for SVs), check each image rendered, caption it, close IGV.
- Report (flexible): write the outputs. When presenting results, the agent may add its own reading of the screenshots, labelled as a reviewer judgement and kept separate from the automatic status.
Modes
Ten modes, each with a prompt and a command, are in GUIDE.md: variant checks (tumor + normal or
tumor-only), SVs, copy number, summaries over many samples, the curated-calls comparison, overview images and
interactive views, sharing the report, counts without IGV, the demo, and a whole project in one command
(--samplesheet). Agents: read GUIDE.md before running the skill for a user.
CLI Reference
# One check: a VCF against a tumor BAM (add --normal for a pair)
python skills/igv-validator/igv_validator.py --vcf calls.vcf --tumor tumor.bam --reference hg38.fa \
--regions genes.bed --output reports/sampleA/snv
# A whole project in one command (see GUIDE.md)
python skills/igv-validator/igv_validator.py --samplesheet samples.csv --reference hg38.fa \
--curated-calls curated.csv --annotation gencode.v44.basic.annotation.gtf.gz
# Demo mode (synthetic data, no user files needed)
python skills/igv-validator/igv_validator.py --demo --output /tmp/igv_demo
# Via the ClawBio runner
python clawbio.py run igv-validator --demo
Every option, with what it does: references/cli-options.md.
Demo
python clawbio.py run igv-validator --demo
Expected output: a report on 6 synthetic variants on two synthetic contigs: 3 supported (an SNV, a 12 bp deletion, a translocation), 1 single-strand artifact, 1 with too few reads and 1 present in the normal. With IGV installed, 7 captioned screenshots in about 10 seconds; without it, counts and report only.
examples/ has a ready samplesheet, gene list and curated table for the demo files (see its README): one
command runs the whole-project workflow on synthetic data and shows a planted wrong curated call as Look first.
Algorithm / Methodology
SNVs are counted from the pileup, indels from CIGAR matches within ±5 bp plus soft-clip rescue, SV breakpoints from split reads and discordant pairs looked up from both ends; each molecule counts once. Flags (normal_support, low_support, low_vaf, strand_bias, read_end, low_depth, germline_site, high_depth, caller_disagrees) set the status: supported, flagged, insufficient or no_coverage. Copy-number mode compares gene depth with the sample-wide depth and with the gene's flanks. The exact rules for every step, flag, status and copy-number check are in references/methodology.md; read it before explaining a flag or status to a user.
Key thresholds / parameters:
- MAPQ >= 20 and base quality >= 20: common somatic-caller defaults (GATK Mutect2 uses MQ 20 / BQ 10-20)
- Minimum 3 supporting reads, 5% VAF: conventional manual-review floors (Barnell et al. 2019 SOP)
- Indel window ±5 bp; SV windows 500 bp (split) / 1 kb (pairs): validated on the osteosarcoma test set (see Maintenance)
Example Queries
- "Validate the KRAS and BRAF calls from my Mutect2 VCF in IGV"
- "Use igv-validator on samples S1 and S2 for KRAS, BRAF and PTEN; compare with my curated calls in curated.csv"
- "Does the GATK deletion in PTEN for sample S1 hold up in the reads?"
- "Make interactive IGV pages for these genes so my PI can zoom in"
- "Is the ODF1 G>T call real? Check tumor and normal reads"
- "Take IGV screenshots of these 10 variants for my PI"
- "Count read support for my PASS variants, no screenshots, I'm on the cluster"
Example Output
# IGV Validator Report
**Input**: `demo_calls.vcf` (6 variant(s) checked) · tumor: demo_tumor · normal: demo_normal
**Skill**: igv-validator 0.1.0
**3 supported, 2 flagged, 1 insufficient**.
IGV screenshots: 7 image(s) in `figures/igv/`.
| ID | Gene | Variant | Tumor support | Normal support | Caller reported (VCF) | Flags | Status |
|---|---|---|---|---|---|---|---|
| V1 | DEMO1 | demo1:3,000 C>A | 18/64 (28.1%) | 0/60 (0.0%) | 18/64 (28.1%) | none | **supported** |
| V2 | DEMO2 | demo1:5,000 A>T | 6/53 (11.3%) | 0/55 (0.0%) | 6/53 (11.3%) | strand_bias | **flagged** |
| V3 | DEMO3 | demo1:7,000 A>T | 2/46 (4.3%) | 0/60 (0.0%) | 12/56 (21.4%) | low_support; low_vaf; caller_disagrees | **insufficient** |
| V4 | DEMO4 | demo1:9,000 12 bp deletion | 15/60 (25.0%) | 0/63 (0.0%) | 15/60 (25.0%) | none | **supported** |
| V5_1 | DEMO5 | demo1:12,000 <-> demo2:5,001 breakend | 14 (6 split, 8 pairs) / 96 fragments | 0 (0 split, 0 pairs) / 99 fragments | - | none | **supported** |
| V6 | DEMO6 | demo1:15,000 A>G | 31/63 (49.2%) | 25/50 (50.0%) | 31/63 (49.2%) | normal_support | **flagged** |
*ClawBio is a research and educational tool. It is not a medical device and does not provide clinical diagnoses. Consult a healthcare professional before making any medical decisions.*
Output Structure
output_directory/
├── report.md # Primary markdown report
├── report.html # Self-contained HTML report (images embedded)
├── result.json # Machine-readable results
├── tables/
│ ├── support_counts.tsv # Tumor/normal read support per variant
│ └── cnv_depth.tsv # Copy-number mode: depth, log2, local ratio, flags per gene (optional, --cnv only)
├── figures/
│ ├── igv/ # Captioned tumor-over-normal screenshots (optional, needs IGV)
│ └── cnv/ # Copy-number mode: depth plots and IGV views (optional, --cnv only)
└── reproducibility/
├── commands.sh # Exact command to reproduce
├── environment.yml # Conda/pip environment snapshot
└── checksums.sha256 # Checksums of the outputs
A summary (--summarize, or each --samplesheet run folder) adds:
summary_folder/
├── summary.html # The one page: curated calls vs IGV, raw calls, links to everything
├── summary.tsv # Every call and field
├── curated_vs_igv.tsv # One row per curated call (with --curated-calls)
├── igv_agreement.tsv # One row per raw caller call
├── summary_settings.json # Options used, so later checks can refresh the page (--project)
├── overview/<sample>_<GENE>.png # One IGV image per gene and sample (--overview; needs IGV)
├── interactive/<sample>_<GENE>.html # Zoomable igv-reports page per gene and sample (--interactive); embeds reads
├── interactive/<sample>.html # Index of a sample's interactive pages
├── igv_validation_full.zip # The whole report, for sharing (not with --no-bundle); contains read data
└── genes.bed, run_log.tsv, samplesheet.csv # --samplesheet runs: genes used, per-check log, a copy of the sheet
Dependencies
Required:
pysam >= 0.22; BAM/VCF/FASTA access and read counting
Pillow >= 10.1; screenshot captions and render checks
Optional:
- IGV desktop >= 2.16 (macOS app, or a Linux
igv.sh / igv command such as an HPC module); screenshots. Tested with 2.16.2 and 2.19.7; IGV <= 2.16 has no currentGenomePath command, so the skill watches IGV's log for the genome load instead. --igv-timeout (default 300 s) covers slow network file systems. Found automatically, or pass --igv-path (a path or a command name). Without it the skill writes counts and the report only.
igv-reports >= 1.17 (pip install igv-reports); --interactive browser pages built on igv.js. Tested with 1.17.0.
matplotlib; depth plots in copy-number mode.
Step by step: validating a whole project
The full walkthrough is in GUIDE.md: install and demo,
choosing genes (curated table, --genes, a BED), writing samples.csv (with the files the curated table was made
from: snv_list, sv_vcf, cnv), checking the reference against the BAMs, the run script, reruns, and runs without a
curated table. In short:
python skills/igv-validator/igv_validator.py --samplesheet samples.csv --reference hg38.fa \
--curated-calls curated.csv --annotation gencode.v44.basic.annotation.gtf.gz [--genes KRAS,BRAF]
# -> igv_reports/<date_time>/summary.html (this run) and igv_reports/index.html (all runs)
Reading the summary: what to trust
The page gives no verdicts: Look first (the reads and the call differ) and Consistent so far (they fit) only
order the review, and every row is checked on its image before it is reported. Details and the key to the images
(IGV colours, depth-plot lines) are in GUIDE.md.
Gotchas
- Indels without
--reference: an insertion a few bases off the call counts if its bases are a rotation of the call's, and a deletion a few bases off counts on its length alone, even outside a repeat. Pass --reference (the --samplesheet workflow requires it) so shifted indels count only when they give the same sequence.
- Counting from the picture: the model will want to count coloured reads in a screenshot. Do not. IGV downsamples and truncates tall panels; numbers must come from
support_counts.tsv.
- Status is not a verdict: the model will want to call
supported variants "true" and flagged ones "false". Do not. The status is a rule-based summary; a germline SNP at the same site, a paralog or a complex allele needs a reviewer. Label any judgement as the agent's reading of the screenshot.
- Wrong genome: IGV with a reference other than the BAMs' build shows every read as mismatched. Always pass the same FASTA the BAMs were aligned to; never fall back to a default genome.
- IGV left running or reused: never send commands to an IGV the user already has open (it wipes their session). The skill starts its own IGV on a free port and closes it; do not bypass this.
- Missing ruler / half-drawn images: IGV can save before it finishes drawing. The skill checks each image and retakes it; do not remove the pause before
snapshot.
- Indels undercounted: reads ending inside a deletion are soft-clipped by aligners. Without
--reference, clip rescue is off and support is conservative; say so.
- Restricted data: with dbGaP or clinical data, do not copy BAMs elsewhere; use
--no-igv on the cluster where the data lives.
- IGV start-up failures keep the log: if IGV does not come up, the report says why and
reproducibility/igv.log holds IGV's own log; send that, not a guess.
- HPC screenshots: IGV needs a display. On a cluster use a remote desktop session (e.g. Open OnDemand "Desktop", not the VS Code app, which has no display), check
igv --version is at least 2.16, and run the demo there first. On a plain compute node use --no-igv.
- Caller counts differ: the model will want to treat a mismatch with the caller's
AD as a bug. Callers realign, cap depth and filter differently (DRAGEN reported 104 reads at a chr4 repeat where 543 MAPQ>=20 reads map). Small SNV differences are normal; large ones usually mean a repeat, which high_depth flags.
- One-sided breakends: Manta and others write each translocation twice. Never count only the first record's side; the skill merges both ends.
- Tumor-only cannot see germline: without a normal, an inherited heterozygous variant looks exactly like a somatic call (about 50% of reads, both strands). Never call a tumor-only
supported variant somatic; say that a normal (or a population database) is needed to tell.
- Caller disagreement is a question, not a verdict:
caller_disagrees often means the caller capped depth, realigned, or used different filters (a chr4 repeat: DRAGEN 32/104 vs 33/470 MAPQ>=20 reads). Look at high_depth and the screenshot before deciding which is right.
- SV VCFs have no gene names: SURVIVOR, Manta and Delly write coordinates only, so
--genes finds nothing there. Use --regions with a BED of the genes: an SV matches if a breakpoint is inside a gene or, for deletions/duplications/inversions, if its span covers the gene (as AnnotSV assigns genes). A run where nothing matches writes a report saying so.
- Copy-number ratios are relative: the ratio compares the gene with its own flanks, so tumor purity, ploidy (whole-genome doubling makes a one-copy loss look like 0.75) and an altered flank all shift it. Read
cnv_disagrees as "look again", and report ploidy with the result.
- Check how the BAMs were aligned:
samtools view -H tumor.bam | grep '^@PG' shows the aligner command. With a GRCh38 reference that includes alt contigs (e.g. the Broad Homo_sapiens_assembly38.fasta), BWA is alt-aware only when <index>.alt sits next to the index; without it, reads in duplicated regions get MAPQ 0 and MAPQ-filtering callers report false losses there. The fix is upstream (alt-aware alignment or a no-alt reference), not in this skill
- Losses called from MAPQ-filtered depth can be mapping artifacts: do not trust a deep deletion just because the caller, the MAPQ >= 20 depth and a downstream curated table all agree on it. Check
ambiguous_mapping first. In regions duplicated on GRCh38 _alt contigs, reads get MAPQ 0 with XA hits on the alternate haplotypes, so every MAPQ-filtering tool sees a "homozygous deletion" while IGV shows full coverage (hollow MAPQ-0 reads).
- Deep deletions in PDX tumors: reads left inside a homozygous deletion are often mouse or mismapped reads;
low_mapq_remaining points at that. Do not count them as evidence against the deletion.
- Whole-VCF runs: the model will want to run on an entire VCF. With no
--genes/--variants, only the first --max-variants (50) records in file order are checked, which are rarely the interesting ones. Ask the user which genes or variants they care about first.
- No reads is not weak evidence:
no_coverage means the BAM has no reads there (a sliced BAM, another sample, another build). Do not report it as "not supported".
- Swapped samples: if the report warns that the normal carries most of the support, stop and check the
--tumor/--normal order before interpreting anything.
- Known gap, clustered mismatches: alt reads that also carry several other mismatches (misaligned reads; the osteosarcoma ODF1 artifact) are not flagged yet. Look for this in the screenshot and say so.
- Hallucinated context: do not add gene-disease claims or VAF interpretations (clonality, purity) that the counts do not show.
Safety
- Local-first: BAMs, VCFs and screenshots stay on the machine; nothing is uploaded
- Disclaimer: Every report includes the ClawBio medical disclaimer
- Audit trail: command, environment and output checksums in
reproducibility/
- No hallucinated science: thresholds are fixed in code and listed above
Agent Boundary
The agent (LLM) dispatches and explains. The skill (Python) executes.
The agent picks the variants with the user, runs the skill, and explains the counts and flags. The agent must NOT change thresholds, invent counts, or present a status as a clinical call.
Integration with Bio Orchestrator
Trigger conditions: the orchestrator routes here when:
- The request mentions IGV, read support, manual review, or "is this variant real"
- The inputs are a VCF plus a tumor/normal BAM pair
Chaining partners: this skill connects with:
nfcore-sarek-wrapper: its somatic VCFs and recalibrated BAMs are direct inputs here
variant-annotation / vcf-annotator: annotate first, then validate the prioritised variants here
clinical-variant-reporter: pass only calls with supported status and reviewer agreement
Maintenance
- Review cadence: monthly, and on every IGV desktop release
- Staleness signals: IGV batch-command or CLI option changes (
--port, --igvDirectory); pysam API changes; new caller VCF conventions for SVs
- Validation record: on a public osteosarcoma WGS dataset (osteosarc.com): 50/50 alt counts identical to
samtools mpileup; 12/12 tumor/normal counts identical to an earlier validated pipeline using real PURPLE and Manta VCFs; 8 previously unseen DRAGEN calls agreed with DRAGEN AD (7 within 1 read); positive/negative controls as expected. Screenshots validated on the demo (3/3 runs) and on real data with the Broad hg38 reference (T0, T1, T2 and two SV callers). Stress-tested on 10 inputs: Mutect2, Strelka, PURPLE, DRAGEN, Manta and ESVEE VCFs; a different sequencing lab; tumor vs another time point's normal; gene selection through VEP CSQ; a 34k-record whole-VCF run; wrong reference, missing chr prefix and swapped samples; and a run while the user's own IGV was open (it received no commands).
- Deprecation: if the skill no longer serves users, archive it to
skills/_deprecated/ with a note explaining why
Citations
- IGV desktop; Robinson et al., Nat Biotechnol 2011: viewer and batch commands
- pysam: htslib bindings used for counting
- Barnell et al., Genet Med 2019, "Standard operating procedure for somatic variant refinement": manual review criteria
- VCF 4.3 specification: BND and symbolic SV notation
1---2name: igv-validator3description: >-4 Read-level validation of variant calls from any VCF, tumor/normal or tumor-only:5 counts read support in the BAMs (SNVs, indels, SV breakpoints), compares it with6 the caller's reported counts, flags artifact patterns, takes one IGV screenshot7 per variant and writes a report.8license: MIT9metadata:10 source: https://skillmd.com/skills/clawbio/igv-validator11 version: "0.1.0"12 author: mgdouq-sudo13 domain: genomics14 tags:15 - igv16 - variant-validation17 - somatic18 - tumor-normal19 - bam20 - structural-variants21 inputs:22 - name: vcf23 type: file24 format:25 - vcf26 - vcf.gz27 description: Somatic calls from any caller (Mutect2, Strelka, DRAGEN, Manta tested)28 required: true29 - name: tumor_bam30 type: file31 format:32 - bam33 - cram34 description: Tumor alignments, indexed (.bai/.crai)35 required: true36 - name: normal_bam37 type: file38 format:39 - bam40 - cram41 description: Matched normal alignments, indexed (omit for tumor-only mode)42 required: false43 - name: reference44 type: file45 format:46 - fasta47 description: Indexed reference FASTA the BAMs were aligned to (needed for screenshots and indel clip rescue)48 required: false49 - name: cnv_segments50 type: file51 format:52 - tsv53 - seg54 description: Copy-number mode - GATK called.seg or a table with contig/start/end/log2/cn_call (with --regions)55 required: false56 - name: variants57 type: file58 format:59 - tsv60 description: Optional list of chrom/pos/ref/alt to check (instead of --genes / --pass-only)61 required: false62 outputs:63 - name: report64 type: file65 format:66 - md67 - html68 description: Validation report with per-variant counts, flags and screenshots69 - name: result70 type: file71 format:72 - json73 description: Machine-readable per-variant support counts and flags74 - name: support_counts75 type: file76 format:77 - tsv78 description: Tumor/normal read support table79 dependencies:80 python: ">=3.10"81 packages:82 - pysam>=0.2283 - Pillow>=10.184 demo_data:85 - path: demo/demo_calls.vcf86 description: Synthetic somatic calls (6 variants) on synthetic contigs, with matching synthetic BAMs87 endpoints:88 cli: python skills/igv-validator/igv_validator.py --vcf {vcf} --tumor {tumor_bam} --normal {normal_bam} --reference {reference} --output {output_dir}89 openclaw:90 requires:91 bins:92 - python393 always: false94 emoji: "🔬"95 homepage: https://github.com/ClawBio/ClawBio96 os:97 - darwin98 - linux99 install:100 - kind: pip101 package: pysam102 - kind: pip103 package: Pillow104 trigger_keywords:105 - validate in IGV106 - IGV validation107 - check variant calls in IGV108 - is this mutation real109 - read support for variant110 - tumor normal read counts111 - IGV screenshot of variant112 - validate somatic calls against BAM113 - do the caller calls agree with the reads114 - tumor-only IGV check115---116117# 🔬 IGV Validator118119You are **IGV Validator**, a specialised ClawBio agent for somatic variant validation. Your role is to check whether variant calls are supported by the reads, by counting tumor and normal read support in the BAMs and showing each call in IGV.120121## Trigger122123**Fire this skill when the user says any of:**124- "validate these mutations in IGV" / "IGV validation"125- "check my variant calls in IGV" / "look at this variant in IGV"126- "is this mutation real or an artifact?"127- "how many reads support this variant in tumor and normal?"128- "take IGV screenshots of my variants"129- "validate somatic calls against the BAM" / "manual review of calls"130- "check KRAS / <gene> mutations in the reads"131- "do my caller's calls agree with IGV?" / "tumor-only validation"132133**Do NOT fire when:**134- The user wants variants *called* from FASTQ/BAM: route to `nfcore-sarek-wrapper`135- The user wants functional annotation (VEP, ClinVar, gnomAD): route to `variant-annotation` or `vcf-annotator`136- The user wants ACMG pathogenicity classification: route to `clinical-variant-reporter` / `cnv-acmg-classifier`137- The user wants sequencing QC (FastQC, coverage summaries): route to `multiqc-reporter` / `seq-wrangler`138- Germline variant review in a single normal sample: the flags assume a tumor sample139140## Why This Exists141142**Two uses:**1431. **Faster review and reporting.** Instead of opening IGV, loading BAMs and navigating to each gene for every144 sample, one run gives a page covering all samples and genes: IGV screenshots, depth plots, zoomable interactive145 views and a plain sentence per call. It is reproducible, and a PI or collaborator can review it without IGV.1462. **Catching errors in calls and pipelines.** The reads are counted straight from the BAM and set against what147 the callers and the curated table say, so disagreements stand out. Example (reproduced by the demo's ALTGENE):148 a gene inside a region duplicated on the GRCh38 alternate-haplotype contigs looked homozygously deleted in149 several samples. The reads were there but had MAPQ 0 because the aligner had not been run alt-aware (no150 BWA `.alt` file), so every MAPQ-filtering caller saw no coverage. IGV showed the reads; this skill measured why151 and pointed at the alignment step, which affects every region with alt contigs.152153**What it isn't:** a variant caller or an automatic truth. Copy number from read depth is a simple measure,154tumor-only data cannot separate inherited from somatic variants, and every verdict is a first pass. The images,155depth plots and interactive views are the evidence: judge each result there before reporting it.156157- **Without it**: reviewers open IGV by hand, type each locus, eyeball reads and guess counts from pictures158- **With it**: every call gets exact read counts from the BAM, artifact flags, the caller's own counts next to159 them, and standard images, in minutes160- **Why ClawBio**: counts come from pysam with fixed filters and were cross-checked against samtools and caller161 `AD`; the screenshot shows the evidence, it is never the source of numbers162163## Core Capabilities1641651. **Variant selection**: by gene (`--genes`, from VEP `CSQ`, SnpEff `ANN`, ANNOVAR `Gene.refGene`/`Gene.refGeneWithVer` or `GENE` INFO), by gene coordinates (`--regions` BED, which also works for SV VCFs without gene names), by exact list (`--variants`), or `--pass-only`. The VCF is streamed, so multi-GB whole-genome files are fine1662. **Read counting**: SNVs (pileup), indels (CIGAR match plus soft-clip rescue at the indel edge), SV breakpoints (split reads plus discordant pairs); each DNA molecule counted once1673. **Artifact flags**: support in normal, fewer than 3 reads, under 5% of reads, single-strand support, alt bases mostly near read ends, low depth, a germline allele already at the site, repeat-like excess depth1684. **Caller comparison**: the caller's own counts (FORMAT `AD`, else `AF` x `DP`) for the tumor's VCF column, next to the BAM counts, with a `caller_disagrees` flag1695. **Two modes**: tumor + matched normal, or tumor-only (omit `--normal`); the normal-based checks are skipped in tumor-only mode1706. **Copy-number mode** (`--cnv`): for each gene in `--regions`, the GATK segment call next to the read depth inside the gene versus its flanks, with a depth plot, a `cnv_disagrees` flag, and IGV screenshots for genes that fit a window1717. **IGV screenshots**: an isolated IGV (own port, own settings folder) on the given reference; one tumor-over-normal (or tumor-only) image per variant, captioned with the BAM and caller counts; closed afterwards1728. **Summary** (`--summarize <folder>`): one page over every run's `result.json` under a folder. With `--curated-calls calls.csv` (a CSV/TSV with sample, gene, alteration: the curated table behind a mutational-profile heatmap, after filtering and manual review; `--heatmap` is accepted as another name) it opens on **"Curated calls vs IGV"** (`curated_vs_igv.tsv`): per sample and gene, what the curated call says, what IGV shows in one plain sentence, *Start here* (*Look first* where the reads and the call differ, *Consistent so far* where they fit; never a verdict), a thumbnail and links to the report, overview and interactive view, with a *details* expander for the comparison, reason and review priority. The comparison follows common curated-table rules (SNV/SV before copy number; DEL/AMP only if under 1 Mb or beyond log2 2), judges copy number from the read depth (per GATK segment, reporting depth steps inside a gene), and explains a WT call over a recurrent variant as consistent (recurrent = the same SNV/indel in 3+ samples, each with at least 2 supporting reads, so low-level copies count). Recurrence is a prompt to look, not a germline call: shared variants are often inherited or artifacts, but a somatic hotspot (e.g. KRAS G12D) recurs too, so a curated SNV on a recurrent variant stays consistent and is noted. Below it, folded, **"Raw calls vs IGV"** (`igv_agreement.tsv`): each raw caller call before filtering, in one plain sentence, with the read counts and flags under *details*. A curated row's *report* link opens the sample's copy-number report (or its only report) showing only that gene, with tabs at the top to the sample's other reports (CNV · SNV · SV) that stay on the gene; "show all genes" returns to the full report. In the interactive views the gene track labels each transcript GENE_TRANSCRIPT (e.g. `KRAS_ENST00000256078.10`). Without `--curated-calls`, the raw calls are the main table. `--overview --regions genes.bed` adds one IGV image per gene and sample; `--interactive` adds zoomable pages; `summary.tsv` keeps every call and field1739. **Report**: `report.md`, self-contained `report.html`, `result.json`, counts TSV and a reproducibility bundle174175## Scope176177**One skill, one task.** This skill checks existing calls against the reads and nothing else. It does not call, annotate or classify variants.178179## Input Formats180181| Format | Extension | Required Fields | Example |182|--------|-----------|-----------------|---------|183| VCF | `.vcf`, `.vcf.gz` | CHROM, POS, REF, ALT (BND ALT or SVTYPE/END for SVs) | `demo/demo_calls.vcf` |184| BAM/CRAM | `.bam` + `.bai` | coordinate-sorted, indexed; tumor required, normal optional | `demo/demo_tumor.bam` |185| Reference | `.fa` + `.fai` | same build as the BAMs | `demo/demo_ref.fa` |186| Variant list | `.tsv` | `chrom pos ref alt` (header optional) | `demo/demo_variants.tsv` |187| Regions | `.bed` | `chrom start end [name]`; the name labels the gene | gene bodies from GENCODE or ANNOVAR refGene |188189## Workflow1901911. **Validate** (prescriptive): VCF, both BAMs and their indexes exist; contig names in the VCF are in the BAM headers; reference (if given) has a `.fai`. Stop with a clear message otherwise.1922. **Select** (prescriptive): apply `--variants` / `--regions` / `--genes` (combined with AND) and `--pass-only`; cap at `--max-variants` (default 50) and say how many were skipped.1933. **Classify** (prescriptive): SNV, insertion, deletion, BND (bracket notation, or symbolic `<TRA>`/`<BND>` with `CHR2`/`END` as SURVIVOR and Delly write) or symbolic `<DEL>/<DUP>/<INV>` of at least 1 kb. Other records (MNVs, small symbolic SVs, CNV-only records) are listed as "not evaluable", never counted. Deletions and insertions written out as sequence (as Manta and SURVIVOR often do) are counted like indels, and from 50 bp they count as SVs in the summary and the curated comparison.1944. **Count** (prescriptive): run the counters with MAPQ >= 20, base quality >= 20, no duplicate/secondary/supplementary/QC-fail reads.1955. **Flag** (prescriptive): apply the rules in [`references/methodology.md`](references/methodology.md); derive the automatic status.1966. **Screenshot** (prescriptive): unless `--no-igv` or IGV is not found, start the isolated IGV, take one image per variant (two for SVs), check each image rendered, caption it, close IGV.1977. **Report** (flexible): write the outputs. When presenting results, the agent may add its own reading of the screenshots, labelled as a reviewer judgement and kept separate from the automatic status.198199## Modes200201Ten modes, each with a prompt and a command, are in **[GUIDE.md](GUIDE.md#modes)**: variant checks (tumor + normal or202tumor-only), SVs, copy number, summaries over many samples, the curated-calls comparison, overview images and203interactive views, sharing the report, counts without IGV, the demo, and a whole project in one command204(`--samplesheet`). Agents: read GUIDE.md before running the skill for a user.205206## CLI Reference207208```bash209# One check: a VCF against a tumor BAM (add --normal for a pair)210python skills/igv-validator/igv_validator.py --vcf calls.vcf --tumor tumor.bam --reference hg38.fa \211 --regions genes.bed --output reports/sampleA/snv212213# A whole project in one command (see GUIDE.md)214python skills/igv-validator/igv_validator.py --samplesheet samples.csv --reference hg38.fa \215 --curated-calls curated.csv --annotation gencode.v44.basic.annotation.gtf.gz216217# Demo mode (synthetic data, no user files needed)218python skills/igv-validator/igv_validator.py --demo --output /tmp/igv_demo219220# Via the ClawBio runner221python clawbio.py run igv-validator --demo222```223224Every option, with what it does: [`references/cli-options.md`](references/cli-options.md).225226## Demo227228```bash229python clawbio.py run igv-validator --demo230```231232Expected output: a report on 6 synthetic variants on two synthetic contigs: 3 supported (an SNV, a 12 bp deletion, a translocation), 1 single-strand artifact, 1 with too few reads and 1 present in the normal. With IGV installed, 7 captioned screenshots in about 10 seconds; without it, counts and report only.233234`examples/` has a ready samplesheet, gene list and curated table for the demo files (see its README): one235command runs the whole-project workflow on synthetic data and shows a planted wrong curated call as *Look first*.236237## Algorithm / Methodology238239SNVs are counted from the pileup, indels from CIGAR matches within ±5 bp plus soft-clip rescue, SV breakpoints from split reads and discordant pairs looked up from both ends; each molecule counts once. Flags (`normal_support`, `low_support`, `low_vaf`, `strand_bias`, `read_end`, `low_depth`, `germline_site`, `high_depth`, `caller_disagrees`) set the status: `supported`, `flagged`, `insufficient` or `no_coverage`. Copy-number mode compares gene depth with the sample-wide depth and with the gene's flanks. The exact rules for every step, flag, status and copy-number check are in [`references/methodology.md`](references/methodology.md); read it before explaining a flag or status to a user.240241**Key thresholds / parameters**:242- MAPQ >= 20 and base quality >= 20: common somatic-caller defaults (GATK Mutect2 uses MQ 20 / BQ 10-20)243- Minimum 3 supporting reads, 5% VAF: conventional manual-review floors (Barnell et al. 2019 SOP)244- Indel window ±5 bp; SV windows 500 bp (split) / 1 kb (pairs): validated on the osteosarcoma test set (see Maintenance)245246## Example Queries247248- "Validate the KRAS and BRAF calls from my Mutect2 VCF in IGV"249- "Use igv-validator on samples S1 and S2 for KRAS, BRAF and PTEN; compare with my curated calls in curated.csv"250- "Does the GATK deletion in PTEN for sample S1 hold up in the reads?"251- "Make interactive IGV pages for these genes so my PI can zoom in"252- "Is the ODF1 G>T call real? Check tumor and normal reads"253- "Take IGV screenshots of these 10 variants for my PI"254- "Count read support for my PASS variants, no screenshots, I'm on the cluster"255256## Example Output257258```markdown259# IGV Validator Report260261**Input**: `demo_calls.vcf` (6 variant(s) checked) · tumor: demo_tumor · normal: demo_normal262**Skill**: igv-validator 0.1.0263264**3 supported, 2 flagged, 1 insufficient**.265266IGV screenshots: 7 image(s) in `figures/igv/`.267268| ID | Gene | Variant | Tumor support | Normal support | Caller reported (VCF) | Flags | Status |269|---|---|---|---|---|---|---|---|270| V1 | DEMO1 | demo1:3,000 C>A | 18/64 (28.1%) | 0/60 (0.0%) | 18/64 (28.1%) | none | **supported** |271| V2 | DEMO2 | demo1:5,000 A>T | 6/53 (11.3%) | 0/55 (0.0%) | 6/53 (11.3%) | strand_bias | **flagged** |272| V3 | DEMO3 | demo1:7,000 A>T | 2/46 (4.3%) | 0/60 (0.0%) | 12/56 (21.4%) | low_support; low_vaf; caller_disagrees | **insufficient** |273| V4 | DEMO4 | demo1:9,000 12 bp deletion | 15/60 (25.0%) | 0/63 (0.0%) | 15/60 (25.0%) | none | **supported** |274| V5_1 | DEMO5 | demo1:12,000 <-> demo2:5,001 breakend | 14 (6 split, 8 pairs) / 96 fragments | 0 (0 split, 0 pairs) / 99 fragments | - | none | **supported** |275| V6 | DEMO6 | demo1:15,000 A>G | 31/63 (49.2%) | 25/50 (50.0%) | 31/63 (49.2%) | normal_support | **flagged** |276277*ClawBio is a research and educational tool. It is not a medical device and does not provide clinical diagnoses. Consult a healthcare professional before making any medical decisions.*278```279280## Output Structure281282```283output_directory/284├── report.md # Primary markdown report285├── report.html # Self-contained HTML report (images embedded)286├── result.json # Machine-readable results287├── tables/288│ ├── support_counts.tsv # Tumor/normal read support per variant289│ └── cnv_depth.tsv # Copy-number mode: depth, log2, local ratio, flags per gene (optional, --cnv only)290├── figures/291│ ├── igv/ # Captioned tumor-over-normal screenshots (optional, needs IGV)292│ └── cnv/ # Copy-number mode: depth plots and IGV views (optional, --cnv only)293└── reproducibility/294 ├── commands.sh # Exact command to reproduce295 ├── environment.yml # Conda/pip environment snapshot296 └── checksums.sha256 # Checksums of the outputs297```298299A summary (`--summarize`, or each `--samplesheet` run folder) adds:300301```302summary_folder/303├── summary.html # The one page: curated calls vs IGV, raw calls, links to everything304├── summary.tsv # Every call and field305├── curated_vs_igv.tsv # One row per curated call (with --curated-calls)306├── igv_agreement.tsv # One row per raw caller call307├── summary_settings.json # Options used, so later checks can refresh the page (--project)308├── overview/<sample>_<GENE>.png # One IGV image per gene and sample (--overview; needs IGV)309├── interactive/<sample>_<GENE>.html # Zoomable igv-reports page per gene and sample (--interactive); embeds reads310├── interactive/<sample>.html # Index of a sample's interactive pages311├── igv_validation_full.zip # The whole report, for sharing (not with --no-bundle); contains read data312└── genes.bed, run_log.tsv, samplesheet.csv # --samplesheet runs: genes used, per-check log, a copy of the sheet313```314315## Dependencies316317**Required**:318- `pysam` >= 0.22; BAM/VCF/FASTA access and read counting319- `Pillow` >= 10.1; screenshot captions and render checks320321**Optional**:322- IGV desktop >= 2.16 (macOS app, or a Linux `igv.sh` / `igv` command such as an HPC module); screenshots. Tested with 2.16.2 and 2.19.7; IGV <= 2.16 has no `currentGenomePath` command, so the skill watches IGV's log for the genome load instead. `--igv-timeout` (default 300 s) covers slow network file systems. Found automatically, or pass `--igv-path` (a path or a command name). Without it the skill writes counts and the report only.323- `igv-reports` >= 1.17 (`pip install igv-reports`); `--interactive` browser pages built on igv.js. Tested with 1.17.0.324- `matplotlib`; depth plots in copy-number mode.325326## Step by step: validating a whole project327328The full walkthrough is in **[GUIDE.md](GUIDE.md#step-by-step-validating-a-whole-project)**: install and demo,329choosing genes (curated table, `--genes`, a BED), writing `samples.csv` (with the files the curated table was made330from: `snv_list`, `sv_vcf`, `cnv`), checking the reference against the BAMs, the run script, reruns, and runs without a331curated table. In short:332333```bash334python skills/igv-validator/igv_validator.py --samplesheet samples.csv --reference hg38.fa \335 --curated-calls curated.csv --annotation gencode.v44.basic.annotation.gtf.gz [--genes KRAS,BRAF]336# -> igv_reports/<date_time>/summary.html (this run) and igv_reports/index.html (all runs)337```338339## Reading the summary: what to trust340341The page gives no verdicts: *Look first* (the reads and the call differ) and *Consistent so far* (they fit) only342order the review, and every row is checked on its image before it is reported. Details and the key to the images343(IGV colours, depth-plot lines) are in **[GUIDE.md](GUIDE.md#reading-the-summary-what-to-trust)**.344345## Gotchas346347- **Indels without `--reference`**: an insertion a few bases off the call counts if its bases are a rotation of the call's, and a deletion a few bases off counts on its length alone, even outside a repeat. Pass `--reference` (the `--samplesheet` workflow requires it) so shifted indels count only when they give the same sequence.348- **Counting from the picture**: the model will want to count coloured reads in a screenshot. Do not. IGV downsamples and truncates tall panels; numbers must come from `support_counts.tsv`.349- **Status is not a verdict**: the model will want to call `supported` variants "true" and `flagged` ones "false". Do not. The status is a rule-based summary; a germline SNP at the same site, a paralog or a complex allele needs a reviewer. Label any judgement as the agent's reading of the screenshot.350- **Wrong genome**: IGV with a reference other than the BAMs' build shows every read as mismatched. Always pass the same FASTA the BAMs were aligned to; never fall back to a default genome.351- **IGV left running or reused**: never send commands to an IGV the user already has open (it wipes their session). The skill starts its own IGV on a free port and closes it; do not bypass this.352- **Missing ruler / half-drawn images**: IGV can save before it finishes drawing. The skill checks each image and retakes it; do not remove the pause before `snapshot`.353- **Indels undercounted**: reads ending inside a deletion are soft-clipped by aligners. Without `--reference`, clip rescue is off and support is conservative; say so.354- **Restricted data**: with dbGaP or clinical data, do not copy BAMs elsewhere; use `--no-igv` on the cluster where the data lives.355- **IGV start-up failures keep the log**: if IGV does not come up, the report says why and `reproducibility/igv.log` holds IGV's own log; send that, not a guess.356- **HPC screenshots**: IGV needs a display. On a cluster use a remote desktop session (e.g. Open OnDemand "Desktop", not the VS Code app, which has no display), check `igv --version` is at least 2.16, and run the demo there first. On a plain compute node use `--no-igv`.357- **Caller counts differ**: the model will want to treat a mismatch with the caller's `AD` as a bug. Callers realign, cap depth and filter differently (DRAGEN reported 104 reads at a chr4 repeat where 543 MAPQ>=20 reads map). Small SNV differences are normal; large ones usually mean a repeat, which `high_depth` flags.358- **One-sided breakends**: Manta and others write each translocation twice. Never count only the first record's side; the skill merges both ends.359- **Tumor-only cannot see germline**: without a normal, an inherited heterozygous variant looks exactly like a somatic call (about 50% of reads, both strands). Never call a tumor-only `supported` variant somatic; say that a normal (or a population database) is needed to tell.360- **Caller disagreement is a question, not a verdict**: `caller_disagrees` often means the caller capped depth, realigned, or used different filters (a chr4 repeat: DRAGEN 32/104 vs 33/470 MAPQ>=20 reads). Look at `high_depth` and the screenshot before deciding which is right.361- **SV VCFs have no gene names**: SURVIVOR, Manta and Delly write coordinates only, so `--genes` finds nothing there. Use `--regions` with a BED of the genes: an SV matches if a breakpoint is inside a gene or, for deletions/duplications/inversions, if its span covers the gene (as AnnotSV assigns genes). A run where nothing matches writes a report saying so.362- **Copy-number ratios are relative**: the ratio compares the gene with its own flanks, so tumor purity, ploidy (whole-genome doubling makes a one-copy loss look like 0.75) and an altered flank all shift it. Read `cnv_disagrees` as "look again", and report ploidy with the result.363- **Check how the BAMs were aligned**: `samtools view -H tumor.bam | grep '^@PG'` shows the aligner command. With a GRCh38 reference that includes alt contigs (e.g. the Broad `Homo_sapiens_assembly38.fasta`), BWA is alt-aware only when `<index>.alt` sits next to the index; without it, reads in duplicated regions get MAPQ 0 and MAPQ-filtering callers report false losses there. The fix is upstream (alt-aware alignment or a no-alt reference), not in this skill364- **Losses called from MAPQ-filtered depth can be mapping artifacts**: do not trust a deep deletion just because the caller, the MAPQ >= 20 depth and a downstream curated table all agree on it. Check `ambiguous_mapping` first. In regions duplicated on GRCh38 `_alt` contigs, reads get MAPQ 0 with XA hits on the alternate haplotypes, so every MAPQ-filtering tool sees a "homozygous deletion" while IGV shows full coverage (hollow MAPQ-0 reads).365- **Deep deletions in PDX tumors**: reads left inside a homozygous deletion are often mouse or mismapped reads; `low_mapq_remaining` points at that. Do not count them as evidence against the deletion.366- **Whole-VCF runs**: the model will want to run on an entire VCF. With no `--genes`/`--variants`, only the first `--max-variants` (50) records in file order are checked, which are rarely the interesting ones. Ask the user which genes or variants they care about first.367- **No reads is not weak evidence**: `no_coverage` means the BAM has no reads there (a sliced BAM, another sample, another build). Do not report it as "not supported".368- **Swapped samples**: if the report warns that the normal carries most of the support, stop and check the `--tumor`/`--normal` order before interpreting anything.369- **Known gap, clustered mismatches**: alt reads that also carry several other mismatches (misaligned reads; the osteosarcoma ODF1 artifact) are not flagged yet. Look for this in the screenshot and say so.370- **Hallucinated context**: do not add gene-disease claims or VAF interpretations (clonality, purity) that the counts do not show.371372## Safety373374- **Local-first**: BAMs, VCFs and screenshots stay on the machine; nothing is uploaded375- **Disclaimer**: Every report includes the ClawBio medical disclaimer376- **Audit trail**: command, environment and output checksums in `reproducibility/`377- **No hallucinated science**: thresholds are fixed in code and listed above378379## Agent Boundary380381The agent (LLM) dispatches and explains. The skill (Python) executes.382The agent picks the variants with the user, runs the skill, and explains the counts and flags. The agent must NOT change thresholds, invent counts, or present a status as a clinical call.383384## Integration with Bio Orchestrator385386**Trigger conditions**: the orchestrator routes here when:387- The request mentions IGV, read support, manual review, or "is this variant real"388- The inputs are a VCF plus a tumor/normal BAM pair389390**Chaining partners**: this skill connects with:391- `nfcore-sarek-wrapper`: its somatic VCFs and recalibrated BAMs are direct inputs here392- `variant-annotation` / `vcf-annotator`: annotate first, then validate the prioritised variants here393- `clinical-variant-reporter`: pass only calls with `supported` status and reviewer agreement394395## Maintenance396397- **Review cadence**: monthly, and on every IGV desktop release398- **Staleness signals**: IGV batch-command or CLI option changes (`--port`, `--igvDirectory`); pysam API changes; new caller VCF conventions for SVs399- **Validation record**: on a public osteosarcoma WGS dataset (osteosarc.com): 50/50 alt counts identical to `samtools mpileup`; 12/12 tumor/normal counts identical to an earlier validated pipeline using real PURPLE and Manta VCFs; 8 previously unseen DRAGEN calls agreed with DRAGEN `AD` (7 within 1 read); positive/negative controls as expected. Screenshots validated on the demo (3/3 runs) and on real data with the Broad hg38 reference (T0, T1, T2 and two SV callers). Stress-tested on 10 inputs: Mutect2, Strelka, PURPLE, DRAGEN, Manta and ESVEE VCFs; a different sequencing lab; tumor vs another time point's normal; gene selection through VEP `CSQ`; a 34k-record whole-VCF run; wrong reference, missing `chr` prefix and swapped samples; and a run while the user's own IGV was open (it received no commands).400- **Deprecation**: if the skill no longer serves users, archive it to `skills/_deprecated/` with a note explaining why401402## Citations403404- [IGV desktop](https://igv.org/doc/desktop/); Robinson et al., *Nat Biotechnol* 2011: viewer and batch commands405- [pysam](https://github.com/pysam-developers/pysam): htslib bindings used for counting406- Barnell et al., *Genet Med* 2019, "Standard operating procedure for somatic variant refinement": manual review criteria407- [VCF 4.3 specification](https://samtools.github.io/hts-specs/VCFv4.3.pdf): BND and symbolic SV notation