contextual-entity-disambiguation

name

contextual entity disambiguation

description

Use this skill when the user's request is linguistically vague, uses high-level colloquial categories, or contains latent clinical/business ambiguities. Trigger it for requests like “make the wording unclear,” “implied filters should be tricky,” “filter for nightlife activity,” “check how the model maps group concepts that aren't exact schema labels,” or “test if it resolves 'first' versus 'any' occurrence.” Example trigger: “Use phrases that could map to several categorical groups or patient populations.” Example trigger: “The question should use colloquial shorthand like 'nightlife' or 'over 18' that requires translating concepts into specific database clusters or rules.”

Skill: contextual entity disambiguation

1. Capability Definition & Real Case

• Professional Definition: The capability to resolve linguistic and latent analytical ambiguity—including high-level categorical concepts, entity value clusters, temporal event ordering (first vs. any), and demographic specifications (age at event vs. current age)—into precise, executable SQL predicates by applying domain-standard conventions and exploratory value-discovery probes.
• Dimension Hierarchy: Environment Grounding->Retrieval and Alignment->contextual entity disambiguation

Real Case

[Case 1]

• Initial Environment: A clinical database (EHR) contains a 'diagnoses' table with patient IDs, condition codes, and the age of the patient at the time of the event. A 'patients' table stores the patient's current age. There is ambiguity in whether 'over 18' refers to the diagnosis time or the current time.
• Real Question: How many patients over 18 have atopic dermatitis?
• Real Trajectory: 1. Identify the ambiguity in 'over 18' as potentially referring to current age or age at diagnosis. 2. Probe the schema to find both 'age_at_event' in the diagnoses table and 'current_age' in the patients table. 3. Apply the epidemiological convention that filters for disease prevalence typically anchor on the age at which the condition was identified. 4. Generate the SQL using a 'COUNT(DISTINCT patient_id)' to satisfy the clinical definition of 'How many patients'.
• Real Answer: SELECT count(DISTINCT patient_id) FROM diagnoses WHERE condition_code = 'AD' AND age_at_event > 18;
• Why this demonstrates the capability: This case demonstrates latent intent disambiguation. The agent must decide between two semantically plausible but relationally different filters (current demographics vs. event history) and apply clinical count semantics where 'how many patients' implies unique individuals rather than raw record counts.

---

[Case 2]

• Initial Environment: An EHR database tracks 'first_diagnosis_date' and 'medication_start_date'. The user query involves a negated relationship with a temporal constraint.
• Real Question: How many patients with chronic kidney disease never took heparin before their CKD diagnosis?
• Real Trajectory: 1. Recognize 'never... before their diagnosis' as an event-ordering ambiguity requiring a temporal anchor. 2. Write a subquery to find the minimum date of a CKD diagnosis per patient as the 'first' anchor. 3. Map 'heparin' to the correct target medication code. 4. Execute a relational exclusion comparing medication_date strictly before the derived anchor date.
• Real Answer: SELECT COUNT(DISTINCT T1.patient_id) FROM (SELECT patient_id, MIN(diagnosis_date) as first_ckd FROM diagnosis_logs WHERE condition = 'CKD' GROUP BY patient_id) AS T1 WHERE T1.patient_id NOT IN (SELECT patient_id FROM medication_logs WHERE drug = 'Heparin' AND medication_date < T1.first_ckd);
• Why this demonstrates the capability: This demonstrates resolving event-ordering ambiguity. The phrase 'never... before their diagnosis' requires identifying the 'first' diagnosis as the temporal anchor, which is a non-trivial interpretation move mapped to a complex SQL sequence.

---

[Case 3]

• Initial Environment: A relational database containing a 'checkins_nyc' table with columns for category_name, latitude, longitude, and checkin_time. The schema follows a flat structure typical of location-based social networks, but lacks an explicit 'nightlife' umbrella column.
• Real Question: Show trends in nightlife activity over time.
• Real Trajectory: 1. Identify 'nightlife' as a high-level concept not directly present as a literal in the schema. 2. Call a probe to retrieve unique values from the 'category_name' column using various keywords. 3. Identify a representative discrete cluster of categories: 'Bar', 'Nightclub', and 'Music Venue'. 4. Compose a query that aggregates check-in counts by month for that specific semantic IN-set.
• Real Answer: SELECT date_trunc('month', checkin_time) AS month, COUNT(*) FROM checkins_nyc WHERE category_name IN ('Bar', 'Nightclub', 'Music Venue') GROUP BY month ORDER BY month;
• Why this demonstrates the capability: This case demonstrates the alignment of a vague categorical domain term ('nightlife') to a specific cluster of database values. The agent must successfully navigate a semantic mismatch by discovering which specific cell values constitute the requested umbrella activity, formulating a set-based filter.

Pipeline Execution Instructions

To synthesize data for this capability, you must strictly follow a 3-phase pipeline. Do not hallucinate steps. Read the corresponding reference file for each phase sequentially:

1. Phase 1: Environment Exploration Read the exploration guidelines to discover raw knowledge seeds: references/EXPLORATION.md

2. Phase 2: Trajectory Selection Once Phase 1 is complete, read the selection criteria to evaluate the trajectory: references/SELECTION.md

3. Phase 3: Data Synthesis Once a trajectory passes Phase 2, read the synthesis instructions to generate the final data: references/SYNTHESIS.md