AI instructions for ai-gene-review

# AI instructions for ai-gene-review

## Project Overview

This project is for managing AI reviews of gene annotations. The overall goal is to both
review existing GO annotations using strict defined criteria, and to summarize the resulting
high quality annotations.

## Repository layout

src/
  ai_gene_review/
    schema/
      gene_review.yaml <-- linkml schema for review docs
genes/
  human/
    CFAP300/
      CFAP300-notes.md <-- keep your notes here
      CFAP300-ai-review.yaml <-- the output of your AI review
      CFAP300-notes.md <-- your own notes, edit this, use it like a journal and keep appending.
      CFAP300-uniprot.txt <-- the uniprot record downloaded from the UniProt website (do not edit this file)
      CFAP300-goa.tsv <-- the GO annotation downloaded from the QuickGO API (do not edit this file, no need to view it)
      CFAP300-deep-research.md <-- the deep research for the gene review (do not edit this file, it is automatically generated for you)
      CFAP300-citations.md <-- the citations for the gene review (do not edit this file)
      CFAP300-bioinformatics/ <-- the folder for any bioinformatics analyses (create this if necessary)
      CFAP300-predictions-review.yaml <-- review of computational predictions NOT in GOA (optional)
    <other genes>/
      ...
  worm/
    lrx-1/
  SCHPO/  <-- other orgs use uniprot species codes
      ...
publications/
  PMID_123456.md <-- cached publication text (this should be available for you, DO NOT EDIT)
reactome/
  R-HSA-NNNNNN.md <- cached reactome entry

You can regenerate the derived files by running commands like:

```
just fetch-gene human CFAP300 
```

This makes the uniprot, goa, and publications files. It will also create a stub for the ai-review.yaml if it doesn't exist.

After making edits to the ai-review.yaml file, you can validate the file by running:

```
just validate human CFAP300
```

This ensures that the yaml file is consistent with the schema in `src/ai_gene_review/schema/gene_review.yaml`, and also
that it implements best practices.

To validate all files, run:

```
just validate-all
```

files will be written to reports/validation-all.tsv 

* All gene symbols follow the standard nomenclature for that species. For human, should be HGNC symbols.

## Gene Review Guidelines

Your job is to review existing annotations for a gene, following GO guidelines, and synthesize these with what is known in the literature,
and what can be inferred bioinformatically. The general structure of the review is as follows:

```yaml
id: <uniprot id>
gene_symbol: <HGNC symbol>
taxon:
  id: <NCBI taxon id>
  label: <taxon label>
description: <your own summary of the gene>
references:
  <all relevant reference, including both literature and bioinformatics sources; includes all but not limited to those used in existing_annotations>
existing_annotations:
  <review of existing annotations, using the GO guidelines; should include all annotations from goa.csv>
core_functions:
  <your own summary of the core functions of the gene>
proposed_new_terms:
  <suggestions for new GO terms>
suggested_questions:
  <suggested questions for experts>
suggested_experiments:
  <suggested experiments to elucidate gene function>
```

See the schema and existing files for more details.

When creating a new review, always make sure files are in place:

`just fetch-gene <organism> <gene>`

This creates the uniprot, goa files, and a stub for the gene review.

The next thing is for you to do deep research on that gene and make a GENE-notes.md file, with citations inline (e.g [PMID:12345 title, "<supporting text>"]). In some cases this will have been done ahead of time for you.

## Reviewing existing annotations

You should start with the ai-review.yaml file, where stubs are created for you (from `just fetch-gene <organism> <gene>`). Any PMID cited should be in the publications folder, e.g. `publications/PMID_123456.md`. Review these.

A deep research file should already be present in the gene folder, e.g. `genes/SPECIES/GENE/GENE-deep-research-PROVIDER.md` (where PROVIDER is openai, falcon, perplexity, etc.). This should contain a summary of the literature, and any other information you found useful for the review. There may be irrelevant information in the citations, that is OK. If this is not present, you can generate one using:

```bash
just deep-research SPECIES GENE --provider perplexity
```

This will create a file like `GENE-deep-research-perplexity.md`. You can also make your own notes in `genes/SPECIES/GENE/GENE-notes.md`.

NEVER write your own content and name it `-deep-research-{provider}.md`. If deep research fails, document in `-notes.md` or `-deep-research-manual.md` instead.

Be aware that many GO terms are over-annotations. You should also not take existing annotations as gospel, whether experimental or bioinformatic.
always use a holistic synthesized picture of the gene function that you have obtained from your research.

```yaml
ActionEnum:
    permissible_values:
      ACCEPT:
        description: Accept the existing annotation as-is, no modifications, and retain as representing the core function of the gene
      KEEP_AS_NON_CORE:
        description: Keep the existing annotation as-is, but mark it as non-core. For pleiotropic genes, this may be the developmental
          processes, or other processes that are not the core function of the gene.
      REMOVE:
        description: Remove the existing annotation, as it is unlikely to be correct based on combined evidence
      MODIFY:
        description: The essence of the annotation is sound, but there are better terms to use (use in combination with proposed_replacement_terms).
          if the term is too general, then MODIFY should be used, with a proposed replacement term for the correct specific function.
          sometimes terms can also be overly specific and contorted, so in some cases you might want to generalize
      MARK_AS_OVER_ANNOTATED:
        description: The term is not entirely wrong, but likely represents an over-annotation of the gene
      UNDECIDED:
        description: The annotation is not clear, and the reviewer is not sure what to do with it. ALWAYS USE THIS IF YOU ARE UNABLE TO ACCESS
          RELEVANT PUBLICATIONS
      NEW:
        
```      

## Tools

Use the OLS MCP to find relevant ontology terms, if the terms you need are not in existing_annotations.

## Curation guidelines

Avoid the term `protein binding`, this doesn't tell us anything about the actual function. Instead find a more
informative MF term (e.g for adapter function)

## Isoform and Negation Tracking

The system tracks isoform-specific GO annotations and NOT (negated) annotations:

```yaml
existing_annotations:
# Isoform-specific annotation
- term:
    id: GO:0045892
    label: negative regulation of DNA-templated transcription
  evidence_type: IDA
  original_reference_id: PMID:9815658
  isoform: P19544-1  # UniProt isoform ID - only present for isoform-specific annotations
  review:
    summary: ...

# NOT annotation (negated)
- term:
    id: GO:0045893
    label: positive regulation of DNA-templated transcription
  evidence_type: IDA
  original_reference_id: PMID:9815658
  negated: true  # This is a NOT annotation
  isoform: P19544-1
  review:
    summary: WT1 does NOT activate transcription...
```

- **`isoform`**: UniProt isoform ID (e.g., `P19544-1`) - indicates what isoform was tested
- **`negated`**: Set to `true` for NOT annotations (e.g., `NOT|involved_in` qualifier in GOA)

**Important**: Just because an annotation was made on a specific isoform doesn't mean the function is isoform-specific.
The `isoform` field indicates what was tested, not necessarily what is unique to that isoform.

To backfill isoform info on existing reviews:
```bash
just backfill-isoforms human WT1
just backfill-isoforms-organism human  # all genes in organism
```

See `docs/isoform_tracking.md` for full documentation and `projects/ISOFORMS.md` for genes with notable isoform-specific functions.

## Bioinformatics analyses

In some cases, it may be useful to do additional bioinformatics analyses. To validate gene function. Here are some guidelines:

For a gene-specific analysis, the folder is `<genes/specues/GENE>-bioinformatics/`. You should make this be reproducible. You can do a `uv init`
here and `uv add` for any packages you need.

Never hardcode the results of the script, it's OK for a script to return inconclusive results. Never ever make up results.

**IMPORTANT**: DO NOT write scripts that just tell users to go to a website. If you cannot programmatically call a tool (e.g., requires API keys, browser interaction, or authentication you don't have), then:
1. Be honest about this limitation upfront
2. Write scripts that can parse/process the output from the tool if the user runs it manually
3. Never write misleading code that pretends to do something it doesn't actually do

You can summarize the results of the bioinformatics analyses in the `<GENE>-bioinformatics/RESULTS.md` file. This can be referenced as any other reference
as e.g `file:<SPECIES>/<GENE>/bioinformatics/RESULTS.md`.

## Reviewing Computational Predictions

The `GENE-predictions-review.yaml` file reviews computational/ML predictions that are NOT
in the curated GOA/UniProt annotations. This is separate from `existing_annotations` in the
main review file.

Use the `PredictionReview` class (validated with `-C PredictionReview`):

```bash
uv run linkml-validate -s src/ai_gene_review/schema/gene_review.yaml -C PredictionReview genes/ECOLI/yciO/yciO-predictions-review.yaml
```

### Prediction sources

Track predictions from: DeepECTF, PANTHER/IBA, InterPro2GO, CLEAN, GloEC, MAPred, or any
other computational method that produces GO or EC predictions.

### Assessment categories (from de Crécy-Lagard et al. 2025, PMID:40703034)

| Code | CS | Description |
|------|-----|-------------|
| COR  | 2   | Correct novel prediction |
| CNN  | 2   | Correct but Not Novel (already in training data) |
| LSP  | 2   | Less Precise than existing annotation |
| UNC  | 1   | Uncertain - cannot validate or refute |
| PLI  | 0   | Paralog Incorrect - wrong paralog subfamily |
| NPI  | 0   | Nonparalog Incorrect - refuted by evidence |
| REP  | 0   | Repetition - frequency-biased prediction |

### Error types

- `PARALOG_OVERANNOTATION` - Wrong paralog subfamily (Type 6)
- `PATHWAY_CONTEXT_IGNORED` - Predicted pathway absent from organism
- `FREQUENCY_BIAS` - Model defaults to high-frequency training labels
- `IN_VITRO_NOT_IN_VIVO` - In vitro activity doesn't match biological function
- `TRAINING_DATA_CONTAMINATION` - Prediction already in training data
- See schema for full list

## Page rendering and deployment

The site is deployed from `main` branch at root via GitHub Pages to https://ai4curation.io/ai-gene-review/.

### Gene review HTML
```bash
just render <organism> <gene>    # render one gene
just render-all                  # render all genes (~1200 files)
```
Output: `genes/<org>/<gene>/<gene>-ai-review.html`

### Project pages
Project docs live in `projects/*.md`. Render with:
```bash
just render-projects                          # render all
ai-gene-review render-projects projects/FOO.md -o pages/projects  # render one
```
Output: `pages/projects/<NAME>.html`

**Important:** The project index page (`pages/projects/index.html`) is **manually maintained**. When adding a new project, you must manually add a `<div class="project-card">` entry to the index HTML. The `render-projects` command does NOT update the index.

### Browser app
```bash
just deploy-browser    # update data.js + index.html for the interactive browser
```
Output: `app/`

### CI automation
The `generate-pages` workflow runs on push to main when gene YAMLs, schema, templates, or project markdown change. It renders everything and creates a PR. Pages deploy directly from main — no gh-pages branch needed for the static content.

## General guidelines

* NEVER guess identifiers for terms, genes, publications. Always use the relevant tools or MCPS, or look them up in derived files.
* For files `<GENE>-notes.md`, use literature deep search, and always record provenance for assertions, e.g `[PMID:12345 "<supporting text>"]`

## Support code

There is also support code in `src/ai_gene_review`, see the CLAUDE.md file in that directory for more details
on best practices for working with the code.