dismech: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Disorder Mechanisms Knowledge Base (dismech) - a LinkML-based knowledge base storing disease pathophysiology information. It combines:

1. A LinkML schema defining the data model (src/dismech/schema/dismech.yaml)
2. A knowledge base of disorder YAML files (kb/disorders/*.yaml)
3. HTML rendering for browsable disorder pages (pages/disorders/*.html)

Design Decisions

Before making structural, scope, ontology, BioLink/KGX, or evidence-policy choices, consult the decision register at docs/explanation/design-decisions.md. It records why the project is built the way it is — project scope (what is/isn't a dismech entry), the LinkML schema choice, the constrained ontology set, export-layer-only BioLink reuse, the evidence/provenance policy, curation governance, and a tracked list of open/deferred decisions. Cite it when a recorded decision is relevant; if a decision looks wrong or stale, surface it rather than silently contradicting it. The specifics below in this file remain authoritative for day-to-day curation mechanics.

Skills

Claude Code skills are available in .claude/skills/:

• dismech-terms: Use when selecting, validating, or repairing ontology bindings and term caches.
• dismech-references: Use when curating or validating evidence and references.
• review-hypothesis-exploration: Use when assessing or reconciling a provider hypothesis report, including its datasets, analyses, and artifacts.

Key Commands

# Install dependencies
just install

# Run all QC checks (validation + term validation)
just qc

# Validate all disorder YAML files against schema
just validate-all

# Validate a single disorder file
just validate kb/disorders/Asthma.yaml

# Validate ontology term references in a single file (anti-hallucination check)
just validate-terms kb/disorders/Asthma.yaml

# Validate ontology term references in the schema's dynamic enums
just validate-terms-schema

# Check that no bound term is flagged Not4Curation by its own ontology
just check-not4curation

# Run pytest tests
just pytest-all

# Run a single test
uv run pytest tests/test_data.py -k "test_name" -v

# Generate HTML pages for all disorders
uv run python -m dismech.render --all

# Generate HTML for a single disorder
uv run python -m dismech.render kb/disorders/Asthma.yaml

# Fetch and cache a reference (PMID, DOI, NCT) — NEVER create cache files manually
just fetch-reference PMID:12345678

# Check evidence snippets against the local reference cache (seconds; use this
# in the curation loop — takes any number of files)
just count-verified-snippets kb/disorders/Asthma.yaml

# Pre-PR sweep: schema + terms + references over every changed file in one
# batched pass (slow — run once at the end, not per edit). This is what CI runs.
just validate-disorders kb/disorders/Asthma.yaml kb/disorders/Cholera.yaml

# Reference validation for a single KB entry (also slow; permits full-text matches).
# "kb" distinguishes it from `just validate-research-reference <report.md>`, which
# checks a deep-research report's citations instead (#8841)
just validate-kb-references kb/disorders/Asthma.yaml

# List all available commands
just --list