Module Curation

Use this skill for modules/*.yaml work and for project pages that describe module/pathway curation. The goal is a reusable, defensible biological module, not a flat list of annotations or a species-specific note disguised as a module.

Workflow

1. Read the local context before editing:
   • modules/README.md
   • the target modules/<module>.yaml
   • any adjacent <module>-deep-research-*.md
   • related projects/** batch page(s), if the task is pathway-batch work
   • relevant gene reviews and UniProt/GOA files for concrete members
2. Decide the module boundary before filling YAML:
   • What biological process, complex, reaction chain, or reusable motif is the module?
   • Which genes/proteins are core members, and which are activation context, substrate supply, regulation, upstream/downstream biology, or separate modules?
   • Is this a concrete species/pathway instance or an abstract reusable motif?
   • Does the boundary have at least two substantive parts/roles/steps? If it collapses to one gene, one enzyme, or one reaction, do not create or retain a standalone ModuleReview; record it as pathway/gene curation and fold it into a broader module later.
3. Model the structure:
   • Put module-level process/complex/context terms on module.concepts and module.context.
   • Put molecular functions on leaf annotons[].function, not on a biological-process module just because the member protein has that MF.
   • Use parts for required steps or roles, variant_sets for alternatives, and connections for ordered/causal links.
4. Ground claims with checkable provenance:
   • Use exact UniProt, GO, Rhea, ChEBI, PANTHER PTHR, and PAINT PTN ids.
   • Never guess PTNs or identifiers. Resolve PTNs from local PANTHER/PAINT data or GOA WITH/FROM evidence.
   • Use representative members to orient family-level claims without turning a reusable module into a species-specific member list.
5. Validate and render before committing:
   • uv run linkml-validate -s src/ai_gene_review/schema/gene_review.yaml -C ModuleReview modules/<module>.yaml
   • uv run python -m ai_gene_review.validation.module_validator modules/<module>.yaml
   • just render-module modules/<module>.yaml
   • render any touched project page with uv run ai-gene-review render-projects ...
   • run git diff --check

Reference Files

Load only the reference needed for the decision at hand:

• references/modeling.md — module-vs-annoton placement, parts, variants, locations, exemplars, PTNs, and common anti-patterns.
• references/research-and-grounding.md — module deep research, species/pathway satisfiability checks, gene review integration, and provenance rules.
• references/validation-and-pr.md — validation, rendering, derived QC, cache noise, and PR checklist.

Curation Rules

• Do not create or retain one-part modules. A standalone module needs at least two substantive parts/roles/steps at the modeled boundary; otherwise keep the work as pathway/gene curation or fold it into a broader multi-part module.
• Avoid redundant parent/child context such as both cytoplasm and cytosol unless the distinction is intentional and explained.
• Do not use broad parent processes as the module core when a specific process or reaction step is available. Keep broad terms as prose/context if needed.
• Keep species-specific notes in evidence, notes, project pages, or concrete instantiations; reusable modules should stay species-neutral unless the scope is deliberately concrete.
• Treat deep research as retrieval support, not authority. Every structural claim must still be grounded in identifiers, gene reviews, GOA/UniProt, GO-CAM, literature, or explicit curator judgment.