git:20260905.3e49039 to git:20261001.bf5afd6

56 added, 70 removed. Audit A to A.

---

name: tracking-taxonomy-updates

- description: Track taxonomy changes and triage sequence assignments across NCBI, GTDB, ICTV, and eukaryotic frameworks. Use when comparing releases, resolving renamed taxa, or routing genomes, bins, and contigs by domain.

+ description: Track NCBI, GTDB, ICTV, and eukaryotic taxonomy releases, and route genomes, bins, or contigs to domain classifiers. Use when comparing releases, resolving renamed taxa, or assigning taxonomy.

---

# Tracking Taxonomy Updates

- Use authoritative sources to report taxonomy changes with explicit versions, dates, and provenance.

+ Report taxonomy changes from authoritative sources with explicit versions, dates, and provenance, and assign taxonomy to sequences through a QuickClade domain screen followed by a domain-specific classifier.

+ `SKILL_DIR` is the directory that contains this `SKILL.md`, for example `~/.agents/skills/tracking-taxonomy-updates`.

## Instructions

- 1. Determine scope (domain, timeframe, output type).

- 2. Pull authoritative updates and release notes.

- 3. Extract versioned changes and impacts.

- 4. If assigning taxonomy for any assembly, MAG, SAG, isolate genome, bin set, or contig FASTA, start with a QuickClade first-pass domain screen through the BBTools container. Save both per-input and `percontig` results before choosing downstream tools.

- 5. Route from the QuickClade domain screen:

- - Bacteria or Archaea -> run GTDB-Tk for genome taxonomy. If the GTDB-Tk reference package is missing, set up/download it under the project/reference DB root, set `GTDBTK_DATA_PATH`, and record the release before running classification.

- - Viral or virus-like -> route to `/bio-viromics`; use vConTACT3 for phage/prokaryotic-virus gene-sharing taxonomy and GVClass for giant-virus/Nucleocytoviricota candidates.

- - Eukaryota -> run EukCC for eukaryotic MAG/genome QC and taxonomy context.

- - Mixed, low-confidence, or conflicting domains -> split or flag contigs for manual review before domain-specific classification.

- 6. Normalize IDs and taxonomy strings across tools.

- Convert QuickClade machine output with

- `scripts/quickclade_to_routing.py` so every downstream decision uses the

- documented `domain_routing.tsv` schema.

- 7. Deliver a versioned report with conflicts flagged.

- 8. Submit GTDB-Tk, EukCC, vConTACT3, and GVClass work through

- `scripts/submit_taxonomy.sh`; do not run these compute-heavy commands on a

- login node.

+ ### Release and name changes

- ## Quick Reference

+ 1. Fix the scope: domains, timeframe, and output type.

+ 2. Pull release notes and current releases from the sources in [reference/sources.md](reference/sources.md). The snapshots in [reference/last-verified-snapshots.md](reference/last-verified-snapshots.md) are examples; re-check the sources for any "latest" claim.

+ 3. Extract versioned changes and their impact, using stable identifiers from [reference/ranks-and-identifiers.md](reference/ranks-and-identifiers.md).

+ 4. Deliver a versioned report from [reference/report-template.md](reference/report-template.md) with conflicts flagged.

- | Task | Action |

- |------|--------|

- | Sources | See `reference/sources.md` |

- | Tools | See `reference/tools.md` |

- | IDs/ranks | See `reference/ranks-and-identifiers.md` |

- | Report template | See `reference/report-template.md` |

- | QA checklist | See `reference/qa-checklist.md` |

- | Release snapshots at authoring time | See `reference/last-verified-snapshots.md` (examples only — re-check sources for "latest") |

- | Environment | Use the project's pinned Pixi environment and record its lockfile |

- | Normalize QuickClade | `uv run --script skills/tracking-taxonomy-updates/scripts/quickclade_to_routing.py quickclade.tsv --sample-id S1 --output domain_routing.tsv` |

- | Submit downstream classification | `SLURM_ACCOUNT=... scripts/submit_taxonomy.sh gtdbtk bins results/taxonomy/gtdbtk` |

+ ### Taxonomy assignment

- ## Domain Triage Contract

+ 1. Run QuickClade first on any assembly, MAG, SAG, isolate genome, bin set, or contig FASTA, through the BBTools container with `percontig` ([reference/tools.md](reference/tools.md)). Skip it only when the user supplies a trusted domain label and asks to skip triage. QuickClade routes; it is not the final authority.

+ 2. Convert the QuickClade machine output into `domain_routing.tsv`:

- QuickClade is the required first pass for sequence-to-taxonomy assignment unless the user explicitly supplies a trusted domain label and asks to skip triage. It is a router, not the final authority.

+ ```bash

+ uv run --script "$SKILL_DIR/scripts/quickclade_to_routing.py" \

+ results/taxonomy/quickclade_percontig.tsv \

+ --sample-id S1 --output results/taxonomy/domain_routing.tsv

+ ```

- Persist:

- - `results/taxonomy/quickclade_percontig.tsv`

- - `results/taxonomy/domain_routing.tsv`

- - downstream tool outputs under `results/taxonomy/{gtdbtk,eukcc,vcontact3,gvclass}/`

+ 3. Route each row:

+ - Bacteria or Archaea: GTDB-Tk. If the reference package is missing, install it under the project or shared database root, set `GTDBTK_DATA_PATH`, record the release, and pass `gtdbtk check_install` before classifying.

+ - Phage or prokaryotic virus: `/bio-viromics`, then vConTACT3.

+ - Giant virus or Nucleocytoviricota: `/bio-viromics`, then GVClass plus a marker-gene phylogeny.

+ - Eukaryota: EukCC.

+ - Mixed, low-confidence, or conflicting domains: split or flag the contigs for manual review before any domain-specific tool.

+ 4. Submit GTDB-Tk, EukCC, vConTACT3, and GVClass through the scheduler, never on a login node:

- Minimum `domain_routing.tsv` columns:

- - `sample_id`

- - `query_id`

- - `contig_id`

- - `quickclade_domain`

- - `quickclade_taxonomy`

- - `quickclade_confidence`

- - `route`

- - `downstream_tool`

- - `review_flag`

- - `notes`

+ ```bash

+ SLURM_ACCOUNT=<account> "$SKILL_DIR/scripts/submit_taxonomy.sh" gtdbtk bins results/taxonomy/gtdbtk

+ ```

+ The template [templates/taxonomy-tool.sbatch](templates/taxonomy-tool.sbatch) requests 16 CPUs, 64 GB, and 24 h, and passes `$SLURM_CPUS_PER_TASK` as the thread count to every tool. It needs `GTDBTK_DATA_PATH`, `EUKCC2_DB`, or `VCONTACT3_DB` for the matching tool; set `GTDBTK_EXTENSION` when genome files do not end in `.fa`. sbatch reads `SBATCH_CLUSTERS`, `SBATCH_PARTITION`, and `SBATCH_QOS` from the environment. On Dori, export `SBATCH_CLUSTERS=perceus-00`, `SBATCH_PARTITION=dori`, `SBATCH_QOS=jgi_normal`, and `SLURM_ACCOUNT=grp-org-sc-mgs`, and qualify `squeue`/`sacct` with `-M perceus-00`.

+ 5. Normalize identifiers and taxonomy strings across tools, and flag disagreements between QuickClade, the classifier, and NCBI.

+ Use the project's pinned Pixi environment for every tool and record its lockfile.

## Input Requirements

- - Domain(s) and timeframe

- - Source systems to compare (NCBI/GTDB/ICTV/etc.)

- - Sequences or genomes (for assignment workflows)

+ - For release tracking: domains, timeframe, and the source systems to compare (NCBI, GTDB, ICTV, eukaryotic frameworks).

+ - For assignment: genome, bin, or contig FASTA files, a QuickClade reference spectra file (`QUICKCLADE_REF`), the downstream databases, and a Slurm account.

## Output

- - Versioned taxonomy update summary

- - Conflict report across sources

- - Standardized taxonomy assignment table (when applicable)

- - QuickClade per-contig domain screen and routing table for sequence assignment workflows

+ - Versioned taxonomy update summary and a cross-source conflict report.

+ - For assignment workflows:

+ - `results/taxonomy/quickclade_percontig.tsv` (agent-authored path, written by QuickClade)

+ - `results/taxonomy/domain_routing.tsv` (agent-authored path, written by `quickclade_to_routing.py`) with columns `sample_id`, `query_id`, `contig_id`, `quickclade_domain`, `quickclade_taxonomy`, `quickclade_confidence`, `route`, `downstream_tool`, `review_flag`, `notes`

+ - tool outputs under `results/taxonomy/{gtdbtk,eukcc,vcontact3,gvclass}/`

+ - a standardized assignment table joined on stable identifiers

## Quality Gates

- - [ ] Every “latest” claim includes date, version, and authority

- - [ ] Stable identifiers used for joins (taxids, GTDB IDs)

- - [ ] Provenance captured (tool version, DB release, run date)

- - [ ] QuickClade was run first for assembly/MAG/genome assignment workflows, with container tag and reference spectra recorded.

- - [ ] Per-contig QuickClade results were persisted and used to choose downstream tools.

- - [ ] Bacteria/Archaea routes include GTDB-Tk outputs and the GTDB reference release; missing GTDB-Tk databases were installed or explicitly reported as blockers.

- - [ ] Viral routes distinguish phage/prokaryotic viruses from giant-virus/Nucleocytoviricota candidates before choosing vConTACT3 or GVClass.

- - [ ] Eukaryotic routes use EukCC rather than prokaryotic QC/taxonomy tools.

- - [ ] GTDB-Tk, EukCC, vConTACT3, and GVClass were submitted through the scheduler, with post-run non-empty output checks.

+ - [ ] Every "latest" claim names the authority, version, and date.

+ - [ ] Joins use stable identifiers (NCBI taxids, GTDB genome IDs), not names.

+ - [ ] Provenance lists tool versions, database releases, container tag and digest, and run dates.

+ - [ ] QuickClade ran first, per contig, and its routing table chose the downstream tools.

+ - [ ] Bacterial and archaeal routes report GTDB-Tk output and the GTDB release, or report the missing database as a blocker.

+ - [ ] Viral routes separate prokaryotic viruses (vConTACT3) from giant-virus candidates (GVClass).

+ - [ ] Eukaryotic routes use EukCC, not prokaryotic QC or taxonomy tools.

+ - [ ] Classifiers ran through the scheduler with explicit thread counts, and outputs were checked as non-empty.

+ - [ ] Items in [reference/qa-checklist.md](reference/qa-checklist.md) pass.

## Examples

- ### Example 1: Update scan scope

```text

Domains: Bacteria + Archaea

Timeframe: last 12 months

Output: summary table + pipeline impact notes

```

## Troubleshooting

- **Issue**: Conflicting taxonomy between sources

- **Solution**: Report both with explicit conflict flags and provenance.

+ **Issue**: Sources disagree on a taxon.

+ **Solution**: Report both assignments with conflict flags and provenance.

- **Issue**: Missing stable IDs

- **Solution**: Resolve via TaxonKit and capture merged/deleted taxid warnings.

+ **Issue**: Stable identifiers are missing.

+ **Solution**: Resolve names with TaxonKit and report merged or deleted taxid warnings.

+ **Issue**: vConTACT3 exits with "No database path provided (--db-path)".

+ **Solution**: Run `vcontact3 prepare_databases --get-version latest --set-location DIR` and export `VCONTACT3_DB=DIR` before submitting.