FHIR Questionnaire Skill

⚠️ CRITICAL RULES - READ FIRST

NEVER suggest LOINC or SNOMED CT codes from memory or training data. ALWAYS use the search and query scripts in this skill.

When any clinical code is needed:

1. For clinical questions/observations: ALWAYS run python scripts/search_loinc.py "search term" FIRST
2. For clinical concepts/conditions: ALWAYS run python scripts/search_snomed.py "search term" FIRST
3. ONLY use codes returned by the scripts
4. If search fails or returns no results, DO NOT make up codes

Clinical codes from AI memory are highly unreliable and will cause incorrect clinical coding.

Network Access Requirements

Requires whitelisted network access:

• clinicaltables.nlm.nih.gov (LOINC search)
• tx.fhir.org (FHIR terminology server for LOINC answer lists and SNOMED CT search)

If network access fails, STOP. Do not suggest codes.

Essential Scripts (Use These Every Time)

1. Search LOINC Codes

ALWAYS run this before suggesting any LOINC code (clinical questions/observations):

python scripts/search_loinc.py "depression screening"
python scripts/search_loinc.py "blood pressure" --format fhir

2. Search SNOMED CT Codes

ALWAYS run this before suggesting any SNOMED CT code (clinical concepts/conditions):

python scripts/search_snomed.py "diabetes"
python scripts/search_snomed.py "hypertension" --format fhir
python scripts/search_snomed.py "diabetes mellitus" --semantic-tag "disorder"

Note: The --semantic-tag filter works best when the semantic tag appears in the display name (e.g., "Diabetes mellitus (disorder)").

3. Find Answer Options

For questions with standardized answers:

python scripts/query_valueset.py --loinc-code "72166-2"
python scripts/query_valueset.py --loinc-code "72166-2" --format fhir

4. Validate Questionnaire

Before finalizing:

python scripts/validate_questionnaire.py questionnaire.json

Templates

Start with assets/templates/:

• minimal.json - Bare bones structure
• basic.json - Simple questionnaire
• advanced.json - Complex with conditional logic

Workflows

Standardized Clinical Instruments (PHQ-9, GAD-7, etc.)

# Step 1: Find panel code (NEVER skip this)
python scripts/search_loinc.py "PHQ-9 panel"

# Step 2: Find answer options
python scripts/query_valueset.py --loinc-code "FOUND-CODE" --format fhir

# Step 3: See examples/templates
# Check references/examples.md for complete implementations

Custom Organizational Questionnaires

# Step 1: Start with template
cp assets/templates/advanced.json my-questionnaire.json

# Step 2: For any clinical questions, search LOINC
python scripts/search_loinc.py "body weight"

# Step 3: Add answer options if available
python scripts/query_valueset.py --loinc-code "FOUND-CODE"

# Step 4: For custom questions without LOINC results, use inline answerOptions
# (no coding system needed - just code + display)