Tracking Taxonomy Updates

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

Release and name changes

1. Fix the scope: domains, timeframe, and output type.
2. Pull release notes and current releases from the sources in reference/sources.md. The snapshots in 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.
4. Deliver a versioned report from reference/report-template.md with conflicts flagged.

Taxonomy assignment

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). 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:

   uv run --script "$SKILL_DIR/scripts/quickclade_to_routing.py" \
     results/taxonomy/quickclade_percontig.tsv \
     --sample-id S1 --output results/taxonomy/domain_routing.tsv

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:

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

   The template 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

• 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 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 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 pass.

Examples

Domains: Bacteria + Archaea
Timeframe: last 12 months
Output: summary table + pipeline impact notes

Troubleshooting

Issue: Sources disagree on a taxon. Solution: Report both assignments with conflict flags and provenance.

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.