Skip to content

KalarisLabs/Myriad / skills/optimize-hifi-diploid-assembly

optimize-hifi-diploid-assembly

Verified

Activate when an agent must generate, compare, quality-control, or select a diploid PacBio HiFi de novo genome assembly using hifiasm; when requests mention HiFi read assembly, haplotype-resolved assembly, hifiasm parameter optimization, primary and alternate contigs, trio binning, Hi-C phasing, Merqury QV, k-mer completeness, BUSCO, QUAST, contamination screening, assembly Pareto ranking, or reproducible assembly QC.

Mission

Produce a reproducible, haplotype-aware diploid HiFi assembly comparison; select a candidate only when it passes declared quality gates; and emit complete provenance sufficient to rerun every command byte-for-byte.

Activation conditions

Use this skill only for PacBio HiFi reads from a nominally diploid isolate or individual. Do not route metagenomes, pooled populations, tumor–normal mixtures, low-accuracy CLR-only reads, or polyploid genomes here. Route those to a different assembly workflow.

Preconditions and fail-closed checks

  1. Resolve every input path and compute SHA-256 checksums before analysis.
  2. Verify FASTQ syntax on all records. Reject files containing unequal sequence/quality lengths, truncated records, or non-IUPAC nucleotide symbols other than N.
  3. Confirm the total input size does not exceed max_total_input_gb when supplied.
  4. Record exact executable versions and the container image digest. If any required executable is absent or unversioned, stop with FAIL_TOOLCHAIN.
  5. Require either no phasing auxiliary data, a complete maternal+paternal k-mer pair, or a complete Hi-C read pair. Reject half-specified phasing inputs.
  6. Never infer genome_size_bp, ploidy, lineage, sex chromosomes, or expected organellar content from filename conventions.

Deterministic procedure

Step 1 — Create immutable run manifest

Write run-manifest.json containing normalized parameters, input checksums, UTC start time, hostname, CPU/RAM inventory, tool versions, container digest, and a randomly generated run UUID. The UUID identifies artifacts but must not affect algorithmic decisions.

Step 2 — Profile reads

Run:

seqkit stats --all --tabular "$READS" > qc/seqkit-stats.tsv

For multiple files, process in lexical path order and aggregate only after per-file validation. Calculate:

  • total bases and reads;
  • read N50 and median length;
  • mean and median Phred quality;
  • fraction of bases below minimum_read_q;
  • approximate sequence coverage = total bases / genome_size_bp.

Decision rules:

  • coverage < 10×: stop FAIL_INSUFFICIENT_COVERAGE;
  • coverage 10–15×: continue but force final status no better than REVIEW;
  • coverage > 300×: stop and require explicit downsampling strategy because extreme depth can distort compute and assembly behavior;
  • more than 5% of bases below Q20: mark READ_QUALITY_WARNING.

Do not trim HiFi reads by default. Remove only structurally invalid records or explicitly supplied adapter contamination with a documented tool and rule.

Step 3 — Build read k-mer database

Choose k deterministically:

  • genome < 500 Mb: k=21;
  • 500 Mb–3 Gb: k=31;
  • > 3 Gb: k=31 unless the estimated unique k-mer count exceeds implementation limits, then stop for operator review.

Run meryl count with the selected k and record the command. Save the database and a histogram. If parental k-mer databases are supplied, verify they use the same k; otherwise stop FAIL_KMER_SIZE_MISMATCH.

Step 4 — Define candidate parameter sets

When candidate_parameter_sets is supplied, use exactly those sets in ascending id order.

Otherwise create this bounded default sweep:

Candidatehifiasm purge level--hom-cov
baseline-p22omitted
conservative-p11omitted
aggressive-p33omitted

Add homcov-observed only when the primary homozygous peak is unambiguous in the k-mer histogram; set --hom-cov to the integer peak location and -l 2. Never guess a peak from a flat or multimodal histogram.

Step 5 — Execute hifiasm candidates

For unphased assembly:

hifiasm -o "$PREFIX" -t "$THREADS" -l "$PURGE_LEVEL" ${HOM_COV_ARG} "$READS"

For trio binning, provide the verified parental k-mer inputs using the hifiasm version-specific trio arguments. For Hi-C phasing, provide the paired Hi-C files using version-specific arguments. Before execution, generate the final command from the installed version's help text; if required flags differ from the pinned command template, stop FAIL_CLI_INCOMPATIBLE instead of improvising.

Convert selected GFA segments to FASTA without reordering segment identifiers. Preserve primary and haplotype outputs separately. A command failure, empty GFA, duplicate segment ID, or zero-length sequence marks that candidate INVALID.

Step 6 — Evaluate every valid candidate identically

For each candidate, run the following in this order:

  1. sequence statistics and assembly span;
  2. QUAST without reference, and additionally with reference_fasta when supplied;
  3. Merqury against the read k-mer database;
  4. BUSCO in genome mode using busco_lineage;
  5. map HiFi reads back with minimap2, sort/index with samtools, and calculate breadth/depth summaries;
  6. screen for suspicious taxonomic contamination using an approved local database workflow, if available. If no approved database is available, emit CONTAMINATION_NOT_ASSESSED and cap status at REVIEW.

Never optimize against N50 alone. Capture at least:

  • total assembly span and span/genome-size ratio;
  • contig count, N50, L50, longest contig;
  • Merqury QV and k-mer completeness;
  • BUSCO complete-single, complete-duplicated, fragmented, and missing percentages;
  • mapped-read fraction, zero-coverage fraction, and extreme-depth fraction;
  • reference-derived misassemblies only when a suitable reference is explicitly provided;
  • haplotype switch/error metrics when phasing truth data are available.

Step 7 — Apply hard gates

A candidate fails if any condition is true:

  • Merqury QV below minimum_merqury_qv;
  • k-mer completeness below minimum_kmer_completeness_percent;
  • BUSCO complete below minimum_busco_complete_percent;
  • BUSCO duplicated above maximum_busco_duplicated_percent, unless a taxonomically justified whole-genome duplication exception is supplied outside this skill;
  • assembly span ratio outside the configured minimum/maximum range;
  • more than 1% of assembly bases have zero mapped-read coverage, unless explicitly attributable to verified auxiliary sequences;
  • contamination screen reports a critical contaminant above the locally approved threshold;
  • output is structurally invalid.

A failed candidate remains in the report but cannot be selected.

Step 8 — Rank passing candidates

Compute normalized metrics among passing candidates only. Higher is better for QV, completeness, BUSCO single-copy completeness, and contiguity; lower is better for duplicated BUSCO, span deviation, zero-coverage fraction, and reference-supported misassemblies.

Use this deterministic lexicographic ranking, not an opaque weighted score:

  1. highest Merqury QV, rounded to 0.01;
  2. highest k-mer completeness, rounded to 0.01%;
  3. highest BUSCO complete-single percentage, rounded to 0.01%;
  4. lowest absolute span-ratio deviation from 1.0, rounded to 0.001;
  5. lowest BUSCO duplicated percentage, rounded to 0.01%;
  6. highest contig N50;
  7. lexical candidate ID.

Select the first candidate. If no candidate passes, emit FAIL and selected_candidate: null.

Step 9 — Package outputs

Create:

output_directory/
  run-manifest.json
  candidate-summary.tsv
  decision.json
  qc/
  candidates/<candidate-id>/
  selected/assembly.fasta
  selected/assembly.sha256
  selected/provenance.json
  logs/

decision.json must contain every gate result, ranking comparison, warning, and the exact reason the winner outranked the runner-up.

Output contract

Return a JSON object with:

  • status: PASS, REVIEW, or FAIL;
  • selected_candidate: candidate ID or null;
  • selected_assembly_path: path or null;
  • candidate_metrics: complete metrics for all candidates;
  • hard_gate_results: per-candidate booleans and reasons;
  • warnings: ordered unique warning codes;
  • provenance: hashes, commands, versions, and runtime manifest path.

Error handling

  • Never silently retry with changed biological parameters.
  • A transient execution retry may occur once with identical command, inputs, environment, and seed; label it in provenance.
  • Preserve partial logs and mark incomplete metrics null with an error code.
  • Never select a candidate with missing required QC metrics.

Validation tests

  1. Schema rejection: non-diploid ploidy must fail before tool execution.
  2. Truncated FASTQ: malformed record must produce FAIL_INPUT_FORMAT.
  3. No passing candidate: selection must be null and status FAIL.
  4. Tie-break: equal metrics must resolve by lexical candidate ID.
  5. Tool drift: changed CLI flags must produce FAIL_CLI_INCOMPATIBLE.
  6. Provenance: deleting any command or checksum must fail repository acceptance tests.

Safety and scope

This skill analyzes genomic data and may handle sensitive human sequence information. Enforce local privacy, consent, retention, and access-control requirements. It does not make clinical interpretations, identify individuals, or authorize release of an assembly as a reference standard.

Scientific basis

  • Cheng H. et al. Haplotype-resolved de novo assembly using phased assembly graphs with hifiasm. Nature Methods 18, 170–175 (2021). DOI: 10.1038/s41592-020-01056-5.
  • Rhie A. et al. Merqury: reference-free quality, completeness, and phasing assessment for genome assemblies. Genome Biology 21, 245 (2020). DOI: 10.1186/s13059-020-02134-9.
  • Gurevich A. et al. QUAST: quality assessment tool for genome assemblies. Bioinformatics 29, 1072–1075 (2013). DOI: 10.1093/bioinformatics/btt086.
  • Seppey M. et al. BUSCO: assessing genome assembly and annotation completeness. Methods in Molecular Biology 1962, 227–245 (2019). DOI: 10.1007/978-1-4939-9173-0_14.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall