Create a Mechanism Module

When to use

• The user asks to create a new kb/modules/*.yaml module.
• A conserved mechanism (a final-common pathway, a recurrent downstream convergence point, a shared drug-target pattern) recurs across ≥2 disorders and is worth checking for consistency via conforms_to.
• The user asks for an Xogenesis module — the formation of a pathological material anatomical entity (cyst, calculus, granuloma, thrombus, amyloid deposit, atheroma, neoplasm, fibrous scar).

Read docs/primers/modules-and-conformance.md first for the conformance mental model (conformance is a consistency check, not DRY inheritance).

Does it clear the module bar?

Only create a module when there is one conserved mechanism reducible to a short linear causal chain with one rate-limiting "key conformance target" node that every conformer funnels through. If the candidate is mechanistically heterogeneous (many unrelated pathways to the same label), it is not a module — consider a Grouping (SHARED_PHENOTYPE) instead.

Module shape

• Validates against the Disease class with category: Module.
• Top-level: name, description, category: Module, creation_date, notes, pathophysiology. Optional: module_categories, treatments, mechanistic_hypotheses, discussions.
• module_categories tags the areas of study the module is relevant to (ModuleCategoryEnum — TOXICOLOGY, PHARMACOLOGY, ONCOLOGY, INFECTIOUS_DISEASE, IMMUNOLOGY, NEUROSCIENCE, DEVELOPMENTAL_BIOLOGY, METABOLISM, AGING) and renders as coloured pills on the module pages. It is a browsing aid, so tag every area that genuinely applies and leave it off when none fits — a wrong pill is worse than no pill. See the Module categories section of CLAUDE.md.
• Nodes bind GO and CL terms only (plus UBERON locations, GO cellular_components). No CHEBI/MONDO term bindings in nodes — describe chemistry/disease in prose. (Exception: a treatments block's therapeutic_agent carries a CHEBI/NCIT id per the treatment schema.)
• Chain of ~5 nodes, each with a role: trigger → amplifier → central_effector → effector → consequence. The central_effector is normally the key conformance target — the disorder-agnostic, rate-limiting step. Every node carries evidence and downstream edges; the notes spell out the disorder-specific substitutions conforming entries make.
• Treatment drug-target pattern (optional but preferred when a drug acts on a specific node): a treatments[] entry uses target_mechanisms with a treatment_effect (INHIBITS/ACTIVATES) pointing at the node name it acts on. Model after cellular_senescence (senolytic) or renal_cystogenesis (tolvaptan).

Evidence discipline (non-negotiable)

Every snippet must be an exact substring of the cited paper's cached abstract. Never fabricate. For each PMID:

uv run linkml-reference-validator cache reference PMID:XXXXXXXX   # (or: just fetch-reference)

Do not hand-write references_cache/*.md. Discard any PMID whose real abstract does not contain your snippet (DR/LLM-suggested citations are frequently wrong — verify each one).

Xogenesis anchor convention (pathological structure formation)

A module whose terminal output is the formation of a pathological material anatomical entity X carries a lightweight, consistent anchor stanza in notes linking to open ontologies (prose CURIEs — no schema slot). Keep it uniform and greppable:

• process genus OGMS:0000061 pathological bodily process — deliberately not GO's anatomical structure formation (that genus presupposes normal programmed development). Sub-type it:
  • OGMS:0000080 pathological transformation — a canonical structure becomes pathological (cyst from a tubule, aneurysm from a vessel wall).
  • OGMS:0000081 pathological derivation — a new formation replaces/adds to prior tissue (granuloma, thrombus, stone, neoplasm).
• output continuant OGMS:0000078 pathological anatomical structure (discrete) or OGMS:0000079 portion of pathological body substance (deposit/stone/fluid).
• species an MPATH:603 (pathological anatomical entity) subtree term for the specific X (cyst MPATH:62, concretion MPATH:614, granuloma MPATH:847, thrombosis MPATH:125, abscess MPATH:608, aneurysm MPATH:90, fibrosis MPATH:181, neoplasm MPATH:218); site a UBERON term.
• SNOMED CT "Morphologically abnormal structure" (49755003) is an external census / gap-detection guide only — never bound in dismech data. If the target X has no MPATH class (e.g. thrombus continuant, amyloid deposit, atheroma), note the OBO gap in the module notes.

Example stanza (in notes):

Xogenesis anchor: the terminal output is a granuloma (MPATH:847), an OGMS:0000078 pathological anatomical structure produced by an OGMS:0000081 pathological derivation; process genus OGMS:0000061.

Verify each anchor CURIE resolves:

uv run runoak -i sqlite:obo:mpath info MPATH:847 -O obo
uv run runoak -i sqlite:obo:ogms info OGMS:0000078 -O obo

Worked Xogenesis modules to copy: renal_cystogenesis, granuloma_formation, thrombogenesis, atherogenesis, amyloidogenesis, nephrolithiasis_crystal_nucleation, cholelithiasis_biliary_supersaturation, fibrotic_response.

Validation

uv run linkml-validate --schema src/dismech/schema/dismech.yaml \
  --target-class Disease kb/modules/<name>.yaml
uv run linkml-term-validator validate-data kb/modules/<name>.yaml \
  -s src/dismech/schema/dismech.yaml -t Disease --labels -c conf/oak_config.yaml
bash scripts/run_reference_validator.sh validate data kb/modules/<name>.yaml \
  --schema src/dismech/schema/dismech.yaml --target-class Disease \
  --config conf/reference_validator_config.yaml

Confirm every snippet is an exact substring of its cached abstract before committing.

Record and connect

1. Do not add the module to a static catalog, and in particular not to a list in CLAUDE.md. There is no module registry there any more — it did not scale and drifted behind kb/modules/, which is the source of truth. A curated ModuleCollection is different: add a module to one only when a published framework or explicit organizing principle supports that membership; collections are not an inventory of every module. Discovery is just list-modules (or ls kb/modules/), which reads the module YAML directly, so choose a descriptive filename and keep the top-level name and description useful for repository search. What that makes load-bearing is the module's own description: slot: write it so it states the causal chain in one sentence, the drug-target pattern if there is one, the key conformance target, how the module is complementary to (not overlapping with) its sibling modules, and — for an Xogenesis module — the OGMS/MPATH/UBERON anchor. That description is the only place a curator will find this, so it must stand alone. Put curation guardrails ("do NOT create a Foo Disease entry", species caveats) in notes:; just list-modules <filter> prints both fields in full and matches on both.
2. Scaffold a history record: just new-history --kind module --slug <name> --event CREATE --outcome changed …
3. Wire real conformers: add conforms_to: "<name>#<Node>" to the matching pathophysiology nodes of the relevant disorder entries, then re-validate.