| name | chart-review-bso-ad-ner |
| description | BSO-AD (Biological / Social / Other determinants of Alzheimer's Disease) NER scope skill. Activates when extracting entities under the BSO-AD ontology — 9 entity-type subtrees covering Demographic, Behavior / Lifestyle, Economic Stability, Education / Literacy, Food, Health Care, Neighborhood, Social and Community Context, and Dementia.
Use this skill in combination with the universal chart-review-ner skill when the task_id is "bso-ad-ner" (or any task with task_kind=ner that pins the BSO-AD ontology).
|
| metadata | {"version":0.1} |
BSO-AD NER scope skill
Companion to chart-review-ner (the universal NER reviewer). This skill
carries the ontology + entity-type guidance for the BSO-AD task. The
universal skill handles the platform workflow (call the right MCP tools
in the right order, faithfulness gating, anchor disambiguation).
The ontology is vendored at references/ontology/concepts.json inside
this skill — the NER MCP server resolves it automatically because
resolveOntologyPath looks here first (after explicit overrides) before
falling back to the env path.
Ontology shape
9 entity-type root labels. The agent should only emit entity_type
values from this set:
| Root label | Approx. concept count |
|---|
Demographic | 35 |
Element_Relevant_to_Behavior_and_Lifestyle | 205 |
Element_Relevant_to_Economic_Stability | 96 |
Element_Relevant_to_Education_and_Literacy | 32 |
Element_Relevant_to_Food | 9 |
Element_Relevant_to_Health_Care | 30 |
Element_Relevant_to_Neighborhood | 61 |
Element_Relevant_to_Social_and_Community_Context | 132 |
Dementia | 60 |
(Use list_entity_types() at run time for the authoritative set + counts.)
Per-entity-type guidance files (lazy load)
Per-entity-type guidance lives at
references/entity_type_guidance/<entity_type>.yaml. Read these
lazily — when you've identified a candidate span and need to
check the exemplars / negative_examples / edge_cases for that
specific entity type before emitting or skipping. The
"Annotation guidance (summary)" section below is usually enough
for read-only reasoning; only open the YAML when you need the
methodologist's specific exemplars or rules.
Each YAML has four sections:
guidance — 2–4 sentences on how to tag this entity typeexemplars — verbatim phrases that SHOULD be taggednegative_examples — phrases that look like the entity but shouldn't
be tagged, each with a reasonedge_cases — specific patterns the methodologist has flagged, each
with a pattern / correct / reason
The methodologist edits these files in the AUTHOR phase of the Studio UI;
they are the authoritative annotation guidance for the current iter. The
prose below is a high-level summary — always defer to the YAML files
when they disagree.
Annotation guidance (summary)
- Demographics: age, gender, race, ethnicity, country-of-origin,
marital status. Prefer the most-specific child (e.g.
Female not
Gender). Numeric ages always need an anchor that extends past the
digits (anchor="age 67", text="67").
- Behavior / Lifestyle: smoking, alcohol, physical activity, sleep,
substance use. These often appear as adjectives or activities; tag the
noun phrase that names the behavior, not the modifier.
- Economic Stability: employment status, income, housing security,
financial strain. Look for negations ("not employed" still maps to
Unemployed).
- Education / Literacy: highest grade, degree, literacy. The
concept_name should match the level, not the institution.
- Food: food security, dietary patterns. This subtree is small (9
concepts) — most clinical notes will yield zero spans here.
- Health Care: access, utilization, insurance. Includes both
"had insurance" and "uninsured" mappings.
- Neighborhood: walkability, crime, environmental hazards. Rare in
notes; usually present only in detailed social histories.
- Social and Community Context: social isolation, social support,
community involvement. The most common Element subtree in clinical
notes about cognitive concerns.
- Dementia: diagnoses, stages, related symptoms. This is the focal
taxonomy for the corpus.
Novel candidates
A span the agent recognizes as a clinically meaningful entity but cannot
map to any concept_name in the ontology should be committed with
status="novel_candidate" and concept_name="". These are not errors —
they're feedback to the methodologist that the ontology may need a new
concept. The chart-review-ner-improve skill (Phase 2) consumes these
to propose ontology extensions.
Out of scope
This skill is read-only context. All writes flow through the
chart_review_ner MCP server. Do not edit concepts.json from within
a run — ontology promotion is a methodologist action invoked from the
Studio UI (Phase 2).
