dismech-terms

Follow the session-wide ontology and cache contract in CLAUDE.md. Use this workflow for each concrete term decision.

Core workflow

1. Inspect the field and its range

Read the relevant slot or class in src/dismech/schema/dismech.yaml. Determine:

• which descriptor or term field owns the binding;
• which ontology prefixes the schema permits;
• whether the field is constrained by a dynamic enum and reachable_from;
• whether a dedicated qualifier or category slot already captures part of the intended meaning.

Do not infer validity from similar-looking entries alone. Nearby entries are useful examples, but the schema and ontology remain authoritative.

2. Choose the validator's ontology source

Check conf/oak_config.yaml before looking up a term. Automated validation uses the adapter configured there and is cache-first.

For prefixes configured with OLS, use OLS for a lightweight search or a local SQLite build when definitions, relationships, or -O obo output are needed:

uv run runoak -i ols:hp search "cognitive impairment"
uv run runoak -i ols:hp info HP:0002014
uv run runoak -i sqlite:obo:hp info HP:0002014 -O obo

-O obo is not implemented by OLS adapters. A local inspection adapter may differ from the configured validation adapter, so never mechanically replace one with the other.

ECTO and XCO are pinned local exceptions. Read Exposure-term decisions before selecting or changing those bindings.

3. Search, inspect, and choose

Search broadly enough to find synonyms, then inspect candidate definitions and ancestry:

uv run runoak -i ols:cl search "regulatory T cell"
uv run runoak -i sqlite:obo:cl info CL:0000815 -O obo
uv run runoak -i sqlite:obo:cl ancestors CL:0000815 -p i

Choose the most specific term that accurately represents the curated claim. Do not choose a narrow term merely because it is available. If only a broad ontology term fits, bind that term and use preferred_term for justified human-readable specificity.

3b. A term suggested by a deep-research report is a lead, not a binding

Reports in research/ suggest CURIEs because the templates ask them to, and they get them wrong in ways that look clean: the CMTX report in #9729 offered MONDO:0010674 (Hunter syndrome) for Charcot-Marie-Tooth X-linked, with 26/26 of its citations verified.

Since deep-research-client 0.2.11 those suggestions are checked as the report is generated. Read the report's ## Term Validation section, or its term_validation: frontmatter, before lifting any CURIE out of it — and add the section to an older report with just validate-research-terms <report>.

Two things the section does not settle, which is the whole of step 3 above:

• whether the term is reachable from the slot's dynamic-enum root, and
• whether it is the right term for the claim, as opposed to a real term named consistently.

It does flag a near-miss when the report names one — the same CMTX report writes "areflexia" beside HP:0001265, which HPO calls Hyporeflexia (Areflexia is HP:0001284). Read those entries as granularity findings, not as paraphrase.

Gene CURIEs are skipped by default there (HGNC uppercase does not resolve in sqlite:obo:hgnc, and ols: resolves it to an unrelated term), so verify those yourself. See docs/deep-research-term-validation.md.

4. Write the descriptor correctly

Keep canonical and display labels distinct:

cell_types:
- preferred_term: CD4+ regulatory T cell
  term:
    id: CL:0000815
    label: regulatory T cell

• term.id is the ontology CURIE.
• term.label exactly matches the canonical ontology label.
• preferred_term is the display label and may preserve clinically or biologically useful nuance not represented by the ontology.

Prefer the canonical label as preferred_term when no extra nuance is needed. Use lowercase hgnc: for HGNC gene CURIEs in this repository.

For common clinical post-composition, follow Descriptor Qualifier Slots in CLAUDE.md; do not recreate temporality, course, severity, or onset in a generic qualifiers list. Follow the root treatment and gain/loss-of-function sections for those schema-modeling decisions.

5. Validate immediately

just validate-terms kb/disorders/YourDisease.yaml

Also run the normal schema validation and the final batched disorder validation required by CLAUDE.md. Treat just validate-terms as authoritative for the configured ontology source and the current cache state.

Interpret failures

Label mismatch

Confirm the identifier against the configured ontology, then update term.label to the canonical label. Do not change preferred_term unless the human-facing wording is also wrong.

XCO terms flagged Not4Curation

RGD keeps XCO terms for hierarchy that it does not want annotated with, and marks them with a related synonym reading Not4Curation — a synonym, not an obsoletion axiom. Such a term exists, has a matching label, and is reachable from XCO:0000000 (the XCO root among the ExposureTerm enum's source_nodes; ExO:0000002 is the ECTO one), so just validate-terms passes it. Twenty-four XCO terms carry the marker, and three of them (XCO:0000294 estrogen/estrogen analog, XCO:0000950 anticonvulsant, XCO:0000561 antidepressant) got into the #8430 tranches before a reviewer noticed (#8472).

just check-not4curation gates this in just qc and CI, so you do not have to remember — but if you are choosing an XCO term by hand, check it first, because the flagged ones are exactly the broad drug-class terms an exposure binding reaches for:

just check-not4curation --list-flagged --prefix XCO   # the whole deny-list
uv run runoak -i sqlite:obo:xco info XCO:0000294      # synonyms include Not4Curation

All three found so far had proper ECTO equivalents (XCO:0000294 → ECTO:9000010 exposure to estrogens), so a flag is a prompt to look in ECTO rather than a dead end.

Specificity Guidelines

Identifier not found

Check the prefix, numeric identifier, obsolescence, and configured adapter. A term found in a newer or different ontology service may still be unavailable to the validator. Select a term visible to the configured source or deliberately update the pinned source through the repository's maintenance workflow.

Dynamic-enum failure

Term existence and enum membership are different checks. A valid ontology term may fall outside the field's allowed ancestor closure. Inspect the field's dynamic enum and its reachable_from root rather than adding the CURIE directly to cache/enums/*.csv.

Use the full OAK-backed audit only when refreshing or investigating membership:

just check-enum-cache

Normal validation uses the faster offline structural check.

Cache integrity or ordering failure

Never type a replacement label, timestamp, or membership row. Read Term-cache recovery, remove only the corrupt derived row when required, re-derive it through validation, and normalize with the sanctioned command.

Common binding patterns

Phenotype

phenotype_term:
  preferred_term: Seizure
  term:
    id: HP:0001250
    label: Seizure

Biological process

biological_processes:
- preferred_term: transforming growth factor beta receptor signaling
  term:
    id: GO:0007179
    label: transforming growth factor beta receptor signaling pathway
  modifier: INCREASED

Disease mapping and coverage

For MONDO coverage and epic-checklist synchronization, the primary disease_term and has_subtypes terms count as curated. A term under mappings.mondo_mappings counts only with skos:exactMatch or skos:narrowMatch; broad, close, and related matches remain cross-references.

Specialized guidance

• Read Exposure-term decisions for ECTO/XCO adapter constraints and the smoking-versus-cigarette and alcohol-consumption-versus-ethanol binding rules.
• Read Term-cache recovery when an integrity, ordering, duplicate, malformed-row, or suspicious-label problem appears.