variant-evidence

Files (1)

• SKILL.md

SKILL.md (first lines)

# Variant And Gene Evidence

Use this skill when the user asks about a specific rsID, allele, gene, genomic
region, observed genotype, absence/reference claim, or whether the user's own
Active Genome Index supports a claim.

## Goal

Answer with the smallest evidence packet needed. Use sample support and
callability checks when the claim requires them.

Run `genomi.describe_context` first if the Active Genome Index is unknown. If an active
Active Genome Index exists, use it for sample-specific lookup. With public-only
context, answer from public/source evidence or ask the user for a file only
when personal evidence is required.

Use `variant.resolve` as the umbrella first lookup when the user's target is an
rsID, coordinate, exact allele, locus, region, or mixed text. It resolves
flexible input, checks the Active Genome Index, gathers existing deterministic
ClinVar/population/reviewed-source facts, and can search explicitly selected
accessible Active Genome Index records with `agi_id` or `include_known_active_genome_indexes`.

> **Convention:** See `skills/conventions/evidence-quality.md`.
> **Convention:** See `skills/_output-rules.md`.

## Contract

Contract:

- Personal variant claims are grounded in the selected Active Genome Index.
- Public-only variant answers are clearly marked public-only.
- Absence/reference claims require callability.
- Positive allele claims use genotype support when answer confidence matters.
- Medical meaning beyond static rows uses Journal source-review memory.

## Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer
when other Genomi capabilities can contribute orthogonal evidence to the same
question. Returning "cannot answer" while applicable capabilities remain
unexamined is a host-agent failure mode.

## Tools

### active_genome_index.classify_genotype_support

Classify whether one exact allele has enough sample support to be used in a personal interpretation.

**Use when**: A user-specific interpretation depends on whether one exact allele is actually supported by Active Genome Index genotype/QC evidence.

**Why necessary**: A reported variant match still needs depth, genotype quality, and allele support before user-specific wording is justified.

**Example prompts**: Does this exact allele have enough support in my Active Genome Index?

**Result semantics**: Returns support_status and evidence_class; the host agent decides whether weak or missing support is a gap.

### active_genome_index.classify_region_callability

Classify whether a region can support reference or absence claims.

**Use when**: A negative, reference, absent-marker, or no-variant claim depends on whether the region was callable.

**Why necessary**: Absence claims require callability; a missing variant in a poorly covered region is not evidence of absence.

**Example prompts**: Can this region support saying a variant was absent?

**Result semantics**: Returns callability_status and support for negative/reference wording; the host agent writes the claim.

### variant.gather_allele_context

Gather existing sample, static, population, and reviewed research evidence for one allele.

**Use when**: The agent needs a consolidated context pack for one exact allele before interpreting or reporting it.

**Why necessary**: Variant reports need sample, static, population, and reviewed-research evidence gathered without recomputing unrelated evidence.

**Result semantics**: Combines stored sample/static/population/research evidence; missing sections are facts for the agent to interpret.

### variant.gather_gene_context

Gather existing sample, ClinVar, and reviewed research evidence for one gene.

**Use when**: a selected gene needs existing sample, ClinVar, and reviewed-research context before synthesis.

**Why necessary**: Gene-level interpretation needs gene-scoped context, which is different from one exact variant lookup.

**Result semantics**: Combines stored gene-scoped sample, static, and reviewed research evidence; absence of a section is not negative evidence by itself.

### variant.find_gene_variants

Find passing variant records in an approved Active Genome Index that overlap
managed GENCODE gene intervals for 1–10 candidate genes.

**Use when**: A public-evidence or phenotype investigation has produced a
small, explicit candidate-gene set and the user has authorized access to the
selected Active Genome Index.

**Why necessary**: A source VCF may not carry gene annotations. This operation
resolves exact symbols through the matching-build GENCODE library, then reads
only those bounded intervals through the Active Genome Index reader.

**Not for**: discovering or ranking candidate genes, interpreting pathogenicity,
consumer genotype-array indexes that lack ref/alt variant records, or claiming
that an empty interval scan rules out disease.

**Result semantics**: `match_basis=gencode_gene_interval_overlap` means only
coordinate overlap. Review `unresolved_genes`, truncation fields, genotype
support, public variant evidence, and clinical confirmation before synthesis.
If the matching GENCODE library is missing, the operation returns
`requires_library_install`; this is a blocked evidence scope, not a negative
genome result.

### variant.resolve

Resolve one variant target and return deterministic public, local sample, and stored evidence facts.

**Use when**: The user gives an rsID, chromosome coordinate, allele string, locus, region, or mixed variant text and needs deterministic facts before interpretation. The agent wants one lookup that can check the selected Active Genome Index and optionally approved previously parsed Active Genome Index records.

**Why necessary**: Precise variant questions need deterministic target resolution before public or personal evidence can be interpreted.

From exon-research/genomi, Apache-2.0.

More from exon-research/genomi