Initiate New Disorder Creation Skill

Overview

Guide the creation of new disorder YAML files in the dismech knowledge base. This skill emphasizes a research-first approach to ensure scientific accuracy and prevent AI hallucinations by requiring deep research queries before file creation.

When to Use

• User asks to create a new disorder/disease entry
• User names a disorder that doesn't exist in kb/disorders/

This skill can also be consulted for ongoing curation of existing disorders.

Workflow

Step 1: Select Disorder Name and Run Duplicate Preflight

Choose the clinically preferred name for the disorder, use title case (e.g. Foo Bar Syndrome). For file names, spaces will. be replaced by underscores, and characters such as apostrophes removed.

Before creating a new disorder file, check all three duplicate surfaces:

1. Most recent knowledgebase: fetch origin/main and search the current upstream disorder YAMLs by MONDO ID, preferred label, and important synonyms.
2. All pull requests: search open, closed, and merged PRs for the same ID and names.
3. All issues: search open and closed issues for the same ID and names.

Use specific identifiers first, then human-readable labels and synonyms:

git fetch origin main

# Knowledgebase on the latest origin/main, not just the local working tree.
git grep -n -i -e "<MONDO_ID>" -e "<preferred disorder name>" origin/main -- kb/disorders || true
git grep -n -i -e "<important synonym>" origin/main -- kb/disorders || true

# PRs and issues across all states.
gh pr list --repo monarch-initiative/dismech --state all \
  --search "\"<MONDO_ID>\" OR \"<preferred disorder name>\"" \
  --json number,title,state,url,headRefName --limit 100
gh issue list --repo monarch-initiative/dismech --state all \
  --search "\"<MONDO_ID>\" OR \"<preferred disorder name>\"" \
  --json number,title,state,url,labels --limit 100

Repeat the PR and issue searches for important synonyms if the first search is empty. If the disorder already exists in the knowledgebase, edit the existing file instead of creating a new one. If an open PR or issue already covers the same disorder, continue there rather than starting duplicate work. If a closed PR or issue appears relevant, inspect it before deciding whether new curation is still needed.

Step 2a: Setup git worktree

The preferred mode of working is to use git worktrees, unless the user has expressed a preference not to do this in advance.

Step 2b: Create initial YAML file

Create an initial yaml file using the underscore form of the disease, e.g.

kb/disorders/Foo_Bar.yaml:

name: Foo Bar
creation_date: "2025-06-12T20:16:27Z"
updated_date: "2025-06-12T20:16:27Z"
category: Complex
disease_term:
  term:
    id: MONDO:nnnnnnn
    label: foo bar  ## mondo name will follow OBO case conventions
parents:
  <yaml list of strings>
has_subtypes:
  <optional yaml list of Subtype objects>
pathophysiology:
  <yaml list of Pathophysiology objects>
phenotypes:
  <yaml list of Phenotype objects>
biochemical:
  <optional yaml list of Biochemical objects>
genetic:
  <optional yaml list of Genetic objects>
environmental:
  <optional yaml list of Environmental objects>
treatments:
  <optional yaml list of Treatment objects>
datasets:

creation_date and updated_date must be ISO 8601/RFC 3339 datetime strings. When editing an existing file, preserve creation_date and bump updated_date.

The objects must follow the LinkML schema in src/dismech/schema.

It can be validated with just validate kb/disorders/Foo_Bar.yaml

This first pass should use textbook knowledge about the disease: you will later refine this.

Step 3: Perform Deep Research (REQUIRED)

Execute at least one deep research query. Always do this via the just command, do not perform your own deep research.

Depending on user preference, use one or more of the following commands

• just research-disorder asta DISORDER_NAME
• just research-disorder perplexity DISORDER_NAME
• just research-disorder falcon DISORDER_NAME
• just research-disorder openai DISORDER_NAME
• just research-disorder cyberian DISORDER_NAME
• just research-disorder openscientist DISORDER_NAME
• just research-disorder claude_code DISORDER_NAME

Use the filesystem-friendly name here.

If the provider you were asked to use is unavailable, do not substitute one by hand and write a paragraph about it into the history record — six committed records already do that, and the substitution is invisible to every query. Ask for a fallback and let the run record it:

just dr_fallback='--fallback' research-disorder falcon DISORDER_NAME

The report is then renamed to whoever actually produced it, and carries fell_back, requested_provider and provider_attempts in its frontmatter. Say in the history record which report you used; the report says who wrote it. See docs/deep-research-provider-fallback.md.

claude_code needs no separate API key. It wraps the local claude CLI as a subprocess (claude --print --output-format json), reusing the Claude Code credential that is already present — CLAUDE_CODE_OAUTH_TOKEN is exported in both dragon-ai.yml and curation-scanner.yml, so it works in CI with no new secret. The provider auto-enables whenever claude is on PATH (disable it with DISABLE_CLAUDE_CODE_PROVIDER=true). For security it restricts the subprocess to read-only research tools (WebSearch, WebFetch) — no filesystem mutations from the research prompt. It captures run provenance (the model used, cost, turn count, web-search count) in a run_metadata field and forces the report inline rather than deferring to a background workflow artifact. This makes it the natural default when you are already inside a Claude Code agentic session and just want a web-grounded report without standing up extra credentials. Requires deep-research-client >= 0.2.7.

falcon requires EDISON_API_KEY or FUTUREHOUSE_API_KEY to be exported in the environment — both names refer to the same key and are accepted interchangeably by deep-research-client. The provider was originally named "FutureHouse Falcon" and later rebranded as "Edison Scientific"; the falcon provider slug in just research-disorder is unchanged. Use whichever key name your environment/secrets manager provides; if you have FUTUREHOUSE_API_KEY that is sufficient. Edison is a large-scale literature agent that performs deep bibliographic research. falcon runs may take 20 minutes or longer. In addition to the narrative report, Edison runs frequently produce artifacts — structured tables, figures, or supplementary documents — that summarise key findings in machine-readable form. When EDISON_API_KEY is set, artifact retrieval happens automatically at the end of just research-disorder falcon …. Artifacts are written to a sub-directory alongside the report:

research/DISORDER_NAME-deep-research-falcon_artifacts/

The report's YAML frontmatter records the trajectory_id used to retrieve them and lists each artifact under the artifacts key. An ## Artifacts section is inserted into the report body for any image artifacts so they render in Markdown viewers. If artifact retrieval was skipped (e.g. EDISON_API_KEY was not set at the time), you can run it later with:

just fetch-research-artifacts <trajectory_id> research/DISORDER_NAME-deep-research-falcon.md

asta requires ASTA_API_KEY to be exported in the environment. Asta behaves more like a literature search agent than a full narrative deep-research agent: its outputs are primarily lists of relevant papers, usually with summaries, evidence snippets, and relevance scores. The just research-disorder asta ... command automatically uses an Asta-specific template tailored for this output style.

openscientist requires OPENSCIENTIST_API_KEY to be exported in the environment. OpenScientist (https://www.openscientist.io) is an autonomous AI research agent from Berkeley Lab that runs iterative hypothesis-driven research using PubMed search and code execution. It produces markdown reports with PMID citations. To set up:

1. Sign up at https://www.openscientist.io
2. Wait for admin approval (required before jobs can run)
3. Generate an API key (shown once in name:secret format)
4. export OPENSCIENTIST_API_KEY="name:secret"

OpenScientist jobs are asynchronous — the provider submits a job, then polls until completion. Jobs are queued server-side and processed sequentially, so wait times depend on queue depth. The API's /report endpoint returns PDF; the provider automatically extracts the markdown final_report.md from the /artifacts ZIP. The artifacts ZIP also contains provenance data (iteration transcripts, generated plots as PNG/JSON) and agent logs.

Timing varies by provider. As a rule of thumb:

• asta usually completes in seconds
• openai and perplexity usually complete within a few minutes
• falcon may take 20 minutes or longer
• cyberian runtime varies with workflow complexity and can also be long-running
• openscientist typically takes 10–30 minutes depending on queue depth and iteration count
• claude_code typically completes in a few minutes — it runs a single bounded agentic session of web searches/fetches rather than a long iterative pipeline, so it is usually faster than falcon/openscientist but with web-grounded (not exhaustive bibliographic) coverage. A representative run (Sarcoidosis, #4761) took ~4m50s, did 11 web searches over 13 turns, returned 24 citations, and cost ~$2 in Claude Code usage. The report's YAML frontmatter records this provenance under run_metadata (models used, web_search_requests, num_turns, total_cost_usd, session_id).

On completion, this will create a file here:

./research/DISORDER_NAME-deep-research-PROVIDER.md

and a separate citations file here:

./research/DISORDER_NAME-deep-research-PROVIDER.md.citations.md

For Edison (falcon) runs, artifacts (figures, structured tables, etc.) are also saved in:

./research/DISORDER_NAME-deep-research-falcon_artifacts/

and referenced in the report's YAML frontmatter under the artifacts key.

For example:

• research/Urticaria-deep-research-openai.md
• research/Urticaria-deep-research-openai.md.citations.md
• research/Urticaria-deep-research-falcon_artifacts/ (falcon only)

You MUST read this before progressing.

Step 3a: Read the report's validation results (REQUIRED)

Reference validation

Every just research-* recipe now resolves the report's citations as part of generating it (deep-research-client >= 0.2.10, backed by the same linkml-reference-validator the KB validators use). The answer is already in the report — read it before you cite anything from that report.

Two places to look:

1. The frontmatter carries a machine-readable summary:

   reference_validation:
     total_references: 24
     verified: 22
     not_found: 2
     confabulation_rate: 0.083
     quotes_checked: 9
     quotes_valid: 8
     relevance_assessed: 22
     on_topic: 19
     off_topic: 1
     off_topic_references:
     - PMID:28123456
     unresolved_references:
     - PMID:99999999
     needs_review: true
   

2. A ## Reference Validation section at the end of the body, with a counts table, an ### Unresolved references list naming each failing identifier, and a ### References that may not be about this subject list.

What to do with it:

• Read needs_review first. It is the one key that cannot give you a false all-clear: it is set when any identifier failed to resolve, or any quote failed to match, or any reference looks off topic. Do not read confabulation_rate as the whole-report signal — it measures identifier resolution and nothing else, so a report whose every PMID exists but whose quotes do not match still reports 0.0.
• Anything under unresolved_references — do not cite it. Either find a different source for the claim or drop the claim. Do not "verify it yourself" by fetching it again and moving on if it happens to work the second time without saying so; if you do re-check one, say in the history record which identifiers you re-checked and what you found.
• A high confabulation_rate (say, above ~0.1) is a signal about the whole report's identifiers, not just the listed ones. Treat the rest of it with extra suspicion and prefer claims you can independently anchor. A low one clears nothing else.
• quotes_valid < quotes_checked means the report attributed a quote to a paper that does not contain it. Read which one before reusing any quoted material from that report.
• Anything under off_topic_references resolved, so it is not a fabrication — it just shares almost none of the report's vocabulary. That is evidence, not a verdict: read the paper before citing or dropping it, since a paper can be relevant in ways its title and abstract do not spell out. Note also that off_topic: 0 is not "all cleared" — a record with no abstract can never be called off topic, so some references are simply undecided.

Reports generated before this existed (most of research/) have no validation section. Add one:

just validate-research-reference research/DISORDER_NAME-deep-research-PROVIDER.md

That rewrites the report in place with a ## Reference Validation section (it does not add a frontmatter summary — on a retro-fitted report, read the section at the bottom). Re-running is safe.

This does not replace anything downstream. It checks the report's citations. The snippet you paste into the KB entry is a different quote in a different file and still needs the normal checks (Step 4 onwards), and none of it catches Named Entity Confusion — run just preflight-dr as usual. The relevance check is not a substitute for that: references are scored against the report's own vocabulary, so a report built around the wrong disease has wrong-disease vocabulary too and scores all of its wrong-disease citations as on topic. See docs/deep-research-reference-validation.md.

Term validation

The same recipes also resolve every ontology CURIE the report suggests (deep-research-client >= 0.2.11, backed by the same linkml-term-validator just validate-terms runs). This is a separate check from the one above, and it catches a different failure: the CMTX report in #9729 had 26/26 citations verified and still offered MONDO:0010674 — Hunter syndrome — as the Charcot-Marie-Tooth X-linked term.

Two places to look, as before: a term_validation: frontmatter block and a ## Term Validation section at the end of the body.

What to do with it:

• Never bind a CURIE listed under unresolved_terms. It does not exist. Find the right term with the dismech-terms skill instead.
• Read needs_review, not confabulation_rate. The rate measures identifier resolution only, so a report whose every CURIE resolves but whose labels name different terms still shows 0.0.
• mislabelled_terms is where the wrong bindings surface. Each entry gives the report's name and the ontology's. Some are harmless paraphrase ("distal weakness" for HP:0002460, Distal muscle weakness). Look for the ones where the ontology label names a different disease, or a different term in the same ontology — a sibling, a parent, a near-miss. The second kind is easy to skim past: the CMTX report writes "areflexia" beside HP:0001265, which HPO calls Hyporeflexia (Areflexia is HP:0001284), and those are clinically distinct.
• unresolvable_prefixes means nothing was checked for that prefix — not that anything is wrong. HGNC is skipped by default; verify gene CURIEs the usual way.
• A clean section is not permission to copy terms across. Term validation says a CURIE exists and is named consistently; it does not say the term is the right one for your claim. Step 5 is unchanged.

Reports generated before this existed have no term section. Add one:

just validate-research-terms research/DISORDER_NAME-deep-research-PROVIDER.md

Like the reference retro-fit, this adds the markdown section but not a frontmatter summary, and re-running is safe. See docs/deep-research-term-validation.md.

Step 3b: GeneReviews Baseline (REQUIRED when applicable)

GeneReviews (https://www.ncbi.nlm.nih.gov/books/NBK1116/) is the authoritative expert-curated clinical reference for Mendelian disorders. Before curating phenotypes, you MUST check whether a GeneReviews article exists for the disease. If one exists, it is the mandatory phenotype baseline — not just a convenient source.

Scope: This step applies primarily to Mendelian (single-gene) disorders. For complex, multifactorial, infectious, or cancer entries where GeneReviews coverage is unlikely, skip directly to Step 4 — the PubMed search below will confirm either way.

1. Search PubMed for a GeneReviews article

curl -sG "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi" \
  --data-urlencode "db=pubmed" \
  --data-urlencode "retmode=json" \
  --data-urlencode "term=<DISEASE_NAME>[TI] GeneReviews[TI]"

If no results, try a broader search: <DISEASE_NAME> GeneReviews[All Fields]

2. If a PMID is found, fetch and cache it

just fetch-reference PMID:XXXXXXXX

3. Tag it in the top-level references: block

references:
  - reference: PMID:XXXXXXXX
    title: "<GeneReviews article title>"
    tags:
      - GeneReviews

You can also run just tag-references after adding the PMID to inline evidence items — the script detects GeneReviews PMIDs from the cached abstract and writes the top-level tag automatically.

4. Cross-reference Clinical Characteristics against your YAML

• Read the cached abstract at references_cache/PMID_XXXXXXXX.md
• Identify every phenotype, anomaly, and comorbidity listed in the Clinical Characteristics section of the abstract
• Compare against your YAML phenotypes: section
• Any GeneReviews-documented phenotype absent from your YAML must either be added (with an HPO term and evidence item quoting the GeneReviews abstract) or explicitly explained as out of scope

Note: The cached abstract captures only the structured PubMed abstract, which is a condensed summary of the full GeneReviews chapter. The full Clinical Characteristics section in the chapter body often lists additional phenotypes not in the abstract. Cross-reference the deep-research artifact (from Step 3) for comprehensive coverage — treat the abstract as the minimum baseline, not the ceiling.

5. Capture drug-safety warnings

GeneReviews often has an Agents/Circumstances to Avoid section. If the abstract mentions any, add a note in the relevant treatment entry's description: and include a GeneReviews evidence item quoting it exactly.

6. Frequency mapping — prose → FrequencyEnum

GeneReviews uses narrative frequency language. Map to the enum as follows:

GeneReviews phrase	FrequencyEnum	HPO range
"virtually all", "most individuals", ">80%"	VERY_FREQUENT	80–100%
"many", "majority", "common", "~50%–79%", ">30%"	FREQUENT	30–79%
"some", "occasional", "uncommon", "~5%–29%"	OCCASIONAL	5–29%
"rare", "few", "<5%", "infrequently reported"	VERY_RARE	1–4%
"isolated reports", "single case"	(omit frequency)	<1%

When frequency is ambiguous, omit frequency: rather than guessing.

7. No GeneReviews article? Document it

If no GeneReviews article exists for the disease, proceed to Step 4 without this baseline. No action needed — the absence itself is not a problem.

---

Step 4: Enhance YAML file with evidence for assestions

Use the results of deep research to enhance the yaml file, providing evidence for as many assertions as possible.

Find the pubmed IDs or DOIs for the papers in the deep research and retrieve these:

• just fetch-reference PMID:nnnnnnn
• just fetch-reference DOI:...

The just fetch-reference command can accept multiple identifiers of different types, such as:

• just fetch-reference PMID:nnnnnnn DOI:nn.nnnn

You can also find additional references relevant to individual assertions, on top of what is in the deep research.

Which citations to take

Work from the report's .citations.md companion file, not from whichever identifiers happened to appear in the prose you read most closely. The report body cites the same paper in several places and omits some of its sources from the narrative entirely, so reading the body alone gives you an arbitrary subset.

Most reports have one; --fallback runs often do not. When the sidecar is missing, sweep the body for identifiers rather than reading linearly, so the set you work from is still the report's and not your reading path's:

grep -o "PMID:[0-9]*" research/DISORDER-deep-research-PROVIDER.md | sort -u

That covers about four in five sidecar-less reports. Where it returns nothing, look for DOIs before giving up. falcon reports are the usual case: they cite by author-year key (martelli2024clinicalspectrumof), which is not a fetchable identifier, and the sidecar-less ones carry no PMID strings at all — but most do carry DOI links, which are fetchable.

grep -oE "doi\.org/10\.[^ ;|,)]+" research/DISORDER-deep-research-PROVIDER.md | sort -u

Fetch those with just fetch-reference DOI:<id>. Then look each one up in PubMed and cite the PMID in preference — a DOI-keyed item is not checked by the gating validator, so the PMID is worth the extra lookup. Only for keys with no DOI beside them do you have to search PubMed by author, year and title words.

Re-running the report is the last resort, not the first: a sidecar-less report usually still names its sources, and a re-run costs a provider call for identifiers already sitting in the file.

Let the claims you are curating choose the references, not a target count. Every assertion you write needs its own citation, so the number falls out of how much of the entry the report actually supports. If a well-covered report leaves you with two or three references, you have almost certainly dropped claims it supported.

Two preferences that are not just taste:

• Prefer a PMID over a DOI for the same paper. DOI: is in skip_prefixes in conf/reference_validator_config.yaml, so a DOI-keyed evidence item is not snippet-checked by the gating validator — CI will not catch a bad quote there. Look the paper up and cite its PMID when it has one.

  When there is genuinely no PubMed record, DOI: is fine, but check the quote yourself rather than leaving it unverified. The body is cached like any other, and the audit tool takes a flag for exactly this:

  just count-verified-snippets --unskip-prefix DOI kb/disorders/YourFile.yaml