Skip to content

ai4curation/ai-gene-review / .claude/skills/module-curation

module-curation

Verified

Curate, review, or repair ai-gene-review ModuleReview YAML documents under modules/, including pathway/module boundary setting, parts and variant modeling, annoton-level molecular functions, representative UniProt/PTN grounding, module deep-research provenance, validation, rendering, and project batch updates.

FileKindSize
SKILL.mdskill md4.8 KB
agents/openai.yamlconfig205 B
references/modeling.mdmarkdown4.9 KB
references/research-and-grounding.mdmarkdown2.4 KB
references/validation-and-pr.mdmarkdown2.7 KB

references/modeling.md

View on GitHub
# Module Modeling

## Choose The Right Level

- `ModuleReview` describes a recursively decomposable biological module:
  pathway, complex, organelle lifecycle, developmental program, molecular
  function program, reaction chain, or abstract motif.
- `ModuleNode` owns the module or submodule identity: `concepts`, `context`,
  `parts`, `variant_sets`, `connections`, and `gocam_associations`.
- `ModuleAnnoton` owns leaf role assertions: participant, molecular function,
  processes, locations, and role description.

For a `BIOLOGICAL_PROCESS` module, place molecular function terms under the leaf
annoton that performs the activity. Do not put an enzyme/adapter/binding MF in
`module.concepts` just because the module has one protein member. Use
module-level MF concepts only when the node itself is intentionally a
`MOLECULAR_FUNCTION` module or motif.

## Concepts And Context

- Use `module.concepts` for ontology/database terms that describe the module
  node as a whole.
- Use `module.context` for shared taxon, cell type, compartment, condition, or
  developmental scope.
- Use leaf `annotons[].locations` when the location applies to a specific
  activity rather than the whole module.
- Avoid redundant parent/child context (`cytoplasm` plus `cytosol`,
  `membrane` plus `plasma membrane`) unless both are needed for a reason recorded
  in `description` or `notes`.

## Parts, Variants, And Connections

- Use `parts` for required steps, roles, subcomplexes, or submodules.
- Use `variant_sets` for alternative implementations along an explicit axis such
  as taxon, compartment, enzyme family, substrate route, developmental context,
  or cell type.
- Use `connections` for relationships between document-scoped ids. For reaction
  chains, add `chaining_status` and `chaining_note` when the advisory CoA
  continuity check needs curator adjudication.
- Do not use a one-part wrapper as a standalone module. The root module boundary
  should expose at least two substantive parts/roles/steps; if the proposed
  scope is one gene, one enzyme, or one reaction, record it as pathway/gene
  curation until it can be folded into a broader module. If one protein has
  multiple mechanistic roles, model those roles explicitly, but do not mistake a
  single leaf annoton for a module.

## Explaining GO-CAM Edges

GO-CAM models compress: a plasma-membrane kinase "directly positively
regulates" a nuclear transcription factor activity with no step between. When
a module covers that pathway, state the missing steps (release, partner
binding, nuclear import), reuse a transport module by `module_ref`
(`karyopherin_nuclear_protein_import` for nuclear entry), and give the bridging
node `module_type: TRANSPORT_STEP`. Then pin the GO-CAM activities at both ends
of the edge with `gocam_associations` (`model` and `activity`) on the module
elements they realize; `just gocam-compartments` reports such edges as
`EXPLAINED` with the module path. Pin only what the module really models (pin a
receptor paralog the module does not list to its node, not to another
receptor's annoton), and say which other gene products the hidden steps need.
See `projects/GOCAM_COMPARTMENTS.md`.

## Participants

- Use `selector_type: GENE` or `GENE_PRODUCT` for a concrete species member.
- Use `FAMILY`, `DOMAIN`, `HOMOLOG_OF`, `ORTHOLOG_OF`, `ANY_WITH_FUNCTION`, or
  `ANY_WITH_DOMAIN` for reusable roles.
- Use `active_units` inside complex descriptors when a complex has role-bearing
  subunits that must remain visible to reasoning.
- Keep activation enzymes, cofactor biosynthesis, transport, regulation, and
  upstream/downstream biology outside the module core unless they are required
  parts of the pathway definition.

## Representative Members And PTNs

- Use `representative_members` on family descriptors for concrete UniProt
  exemplars that orient the reader and satisfy leaf grounding QC.
- Representative members are examples, not an exhaustive species list and not a
  claim that the module is limited to those proteins.
- Use `ancestral_nodes` for the stronger PAINT claim that a function arose at or
  was present in a PANTHER ancestral node and is inherited by descendants unless
  diverged.
- Ground ancestral nodes with exact `PANTHER:PTN...` ids from local canonical
  IBD data under `interpro/panther/<PTHR>/<PTHR>-paint.tsv` or from GOA
  WITH/FROM evidence with `GO_REF:0000033`. Never guess PTN ids.

## Common Anti-Patterns

- Module-level MF term on a process module when the MF belongs to a step.
- Single species-specific enzyme or reaction represented as a standalone module.
- Broad process term as module core when a specific process/reaction term exists.
- Parent and child locations both asserted without explanation.
- Species-specific wording in a reusable module label or description.
- Inflating representative members to every species mentioned in evidence.
- Treating generated deep-research prose as a source of identifiers without
  checking UniProt, GOA, PANTHER, Rhea, ChEBI, GO-CAM, or publications.
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall