draft-from-findings

name	draft-from-findings
description	Convert a populated findings.json (from research skills like pubmed-search / guideline-search) into FHIR R4 Questionnaire item[]. Handles item.type selection, answerOption construction, and item.code population. Use whenever the user says "now add a question about X" after a research turn.

Draft from findings

When to use this

• After a research turn (pubmed-search / guideline-search / cochrane-search) that produced findings.json, when the user asks for the actual question(s) to be added.
• When you need to translate a clinical concept into a patient-facing question.

item.type — pick correctly

item.type	Use it for
boolean	Single yes/no fact ("Have you had a thunderclap headache?").
choice	One-of-N from a closed list (severity, headache type).
open-choice	Choice + free-text other.
integer	Counts (#headaches/month).
decimal	Continuous measurement (weight, kg).
quantity	Number + unit (BP=120 mmHg).
string	Short free text.
text	Multi-line free text.
date	Calendar date with no time.
dateTime	Date + time.
time	Time of day.
url	Full URL.
attachment	Photo / file.
display	Static instructions, no answer.
group	Container for sub-items.

For Likert scales: choice with answerOption[] and itemControl=radio-button. For 0-10 numeric scales: integer with minValue=0 + maxValue=10 + itemControl=slider + sliderStepValue=1.

answerOption construction

For closed lists (severity, frequency), use valueCoding with a codeable concept where possible:

{
  "answerOption": [
    { "valueCoding": { "system": "http://loinc.org", "code": "LA6111-4", "display": "None" } },
    ...
  ]
}

If no good code system exists, use valueString and document why in notes.md.

item.code population

For items that map to a known LOINC observation (e.g. PHQ-9 item 1 = 44250-9), populate item.code = [{ system: "http://loinc.org", code: "..." }]. Use loinc-lookup to verify. Leave empty for truly local items.

linkId style

• Stable, kebab-case, scoped to the item's purpose: headache-onset, phq-1-interest, red-flag-thunderclap.
• Don't renumber on insert. Append to the parent group.
• For instrument items, mirror the published item number when the instrument has one (e.g. phq-1 … phq-9).

Output

A propose-edit using propose-edit skill — either drop the new items into the right group within proposed-questionnaire.json, or emit discrete suggestions.json entries (preferred for small additions).

Pitfalls

• Putting a Likert as integer instead of choice — destroys the answer-option semantics for scoring.
• Inventing LOINC codes. If you can't verify, leave item.code off.
• Free-text on a question that has a published answer set ("which triptan have you tried?" — there's a SNOMED ValueSet for that).