PranavNagrecha/AwesomeSalesforceSkills / skills/admin/clinical-data-requirements
clinical-data-requirements
VerifiedUse this skill when defining clinical data model requirements for Health Cloud: HL7/FHIR data mapping, interoperability requirements, FHIR R4-aligned object activation, CodeableConcept constraints, and middleware translation requirements. NOT for the field-level mapping work itself — use data/fhir-data-mapping. NOT for choosing legacy HC24__ EHR objects vs standard clinical objects — use data/health-cloud-data-model.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.6 KB |
| references/examples.md | markdown | 5.7 KB |
| references/gotchas.md | markdown | 7.9 KB |
| references/llm-anti-patterns.md | markdown | 5.9 KB |
| references/metadata-examples.md | markdown | 4.4 KB |
| references/well-architected.md | markdown | 4.7 KB |
| scripts/check_clinical_data_requirements.pyexecutable | script | 4.4 KB |
| templates/clinical-data-requirements-template.md | markdown | 2.3 KB |
references/llm-anti-patterns.md
View on GitHub# LLM Anti-Patterns — Clinical Data Requirements
Common mistakes AI coding assistants make when generating or advising on clinical data model requirements.
## Anti-Pattern 1: Treating Salesforce as a 1:1 FHIR R4 Implementation
**What the LLM generates:** FHIR integration designs that assume FHIR bundles can be sent directly to Salesforce and stored without transformation, or that Salesforce's FHIR R4 implementation exactly mirrors the HL7 FHIR R4 specification for all resources.
**Why it happens:** Salesforce markets FHIR R4 alignment prominently. LLMs interpret this as full spec conformance. The deliberate deviations (complex type flattening, cardinality caps, mandatory field differences) are implementation details not inferrable from product marketing.
**Correct pattern:**
A middleware layer is always required between the source FHIR system and Salesforce. The middleware must handle: complex type flattening, CodeableConcept truncation at 15 codings, field cardinality normalization, and identifier mapping. Do not design FHIR integrations that bypass middleware.
**Detection hint:** If the integration design shows FHIR bundles flowing directly from EHR to Salesforce without a transformation layer, the middleware requirement is missing.
---
## Anti-Pattern 2: Writing FHIR Patient Demographics to Account Fields
**What the LLM generates:** FHIR Patient resource mapping that writes Patient.name to Account.Name, Patient.telecom to Account.Phone, and Patient.address to Account.BillingAddress.
**Why it happens:** Account.Name and Account.Phone are the obvious field mappings for Patient.name and Patient.telecom in a standard Salesforce CRM model. LLMs apply this direct mapping without knowing the Health Cloud child-object model.
**Correct pattern:**
FHIR Patient demographics map to child objects: PersonName (name), ContactPointPhone/Email (telecom), ContactPointAddress (address). These must be created as child records linked to the Person Account. Writing directly to Account fields bypasses the Health Cloud data model and breaks clinical UI components.
**Detection hint:** If the FHIR Patient mapping writes name/telecom/address fields directly to Account/Contact fields without creating child objects, the Health Cloud data model is being bypassed.
---
## Anti-Pattern 3: Using Legacy or Invented EHR Object Names
**What the LLM generates:** Integration code targeting `HC24__EhrCondition__c` for a new org, or "replacement" objects that do not exist, such as `PatientMedication`, `MedicalProcedure`, `HC24__EhrMedication__c`, or `HC24__EhrLabResult__c`.
**Why it happens:** Pre-Spring '23 tutorials use the packaged objects, and plausible names fill the gaps.
**Correct pattern:** New customers cannot create records in packaged EHR objects that have standard counterparts. Target `HealthCondition`, `MedicationStatement`, `MedicationRequest`, `PatientMedicalProcedure`, `CareObservation`, `PatientImmunization`, and `AllergyIntolerance`. Confirm every object name against the guide or a describe call.
**Detection hint:** Any `HC24__` object in new integration code, or an object name that a describe call does not return.
---
## Anti-Pattern 4: Treating HL7 v2 as Either Unsupported or Native
**What the LLM generates:** Either "Salesforce cannot store HL7 v2 data at all," or "send the ADT message to Salesforce and it will be parsed."
**Why it happens:** The model knows Salesforce speaks REST and JSON, and does not know the clinical data model documents HL7 v2.3 segment mappings.
**Correct pattern:** The guide documents mappings for ADT, ORM, ORU, MDM, VXU, and RDE (HL7 v2.3) segments to standard object fields, and states that a middleware integration solution is required to convert HL7 and FHIR messages. Put a translation layer in front of Salesforce that parses messages and writes the mapped fields.
**Detection hint:** HL7 v2 messages sent straight to the REST API, or a design that discards HL7 v2 sources as unsupported.
---
## Anti-Pattern 5: Overstating What the Org Pref Gates
**What the LLM generates:** "Without FHIR R4 Support Settings, all clinical objects including CareObservation are inaccessible, and the activation is irreversible."
**Why it happens:** The model generalizes from the objects that do need the pref, and adds an irreversibility claim that is not in the guide.
**Correct pattern:** The guide lists objects that need the FHIR-Aligned Clinical Data Model org pref (for example `HealthCondition`, `ClinicalEncounter`, `MedicationRequest`) and objects that do not (for example `CareObservation`, `CodeSet`, `CodeSetBundle`, `PersonName`). Enable the pref first, list what it unlocks, and treat reversibility as a question to confirm, not a fact.
**Detection hint:** `CareObservation` described as gated by the pref, or "irreversible" stated without a source.
---
## Anti-Pattern 6: Mapping `condition.code` as Optional
**What the LLM generates:** A middleware mapping that sends conditions without a code, because `condition.code` is 0..1 in FHIR.
**Why it happens:** The model maps cardinality straight from the FHIR specification.
**Correct pattern:** `HealthCondition.ConditionCodeId` (a lookup to `CodeSetBundle`) is one-to-one in Salesforce. Build the `CodeSet` and `CodeSetBundle` first, and define a rule for code-less source records.
**Detection hint:** A condition mapping with no rule for missing codes.
---
## Anti-Pattern 7: Calling the Portal Requirement an Org Setting
**What the LLM generates:** "Enable FHIR R4 for Experience Cloud in Setup so patients can see their conditions."
**Why it happens:** Many Health Cloud features are org settings, so the model assumes this one is too.
**Correct pattern:** Community users need the FHIR R4 for Experience Cloud Sites permission set to use clinical data model objects on a site. Pair it with sharing for the records each patient may see.
**Detection hint:** Portal designs that name an org setting instead of the permission set.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |