include-instrument

name	include-instrument
description	Decide whether to inline a validated instrument (copy items into Questionnaire.json) versus reference it via subQuestionnaire. Surfaces license + fidelity tradeoffs and records the decision. Use when the user wants to "add PHQ-9" (or any published instrument) to a draft.

Include instrument

When to use this

• The user names a published instrument ("add PHQ-9", "include GAD-7") and you need to actually wire it in.
• A research turn surfaced a candidate instrument the user is about to accept.

Two ways to include

A. Inline (copy items)

Copy the instrument's items directly into the form's item[].

• ✅ Self-contained: the form ships with everything the patient sees.
• ✅ Easy to localize and re-skin.
• ❌ Drifts from the canonical source over time.
• ❌ License risk for non-public-domain instruments.

B. subQuestionnaire reference

Use the SDC subQuestionnaire extension on a display (or group) item:

{
  "linkId": "phq9",
  "type": "display",
  "extension": [{
    "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-subQuestionnaire",
    "valueCanonical": "http://loinc.org/q/44249-1"
  }]
}

• ✅ Renderer pulls the canonical version each time.
• ✅ License-clean: you're referencing, not copying.
• ❌ Renderer support varies. Pin a renderer or test before shipping.

License triage

License	Approach
Public domain (PHQ-9, GAD-7, AUDIT, SF-36 v1)	Inline OK.
Free-with-attribution (NIH PROMIS short forms; many AHRQ)	Inline OK; preserve attribution copy.
Permission required (BDI-II, HADS, some PROMIS CAT)	subQuestionnaire only. Note license in decisions.md.
Trade secret	Don't include. Refuse and explain.

Always cite the source instrument in the form via an instrument-typed citation (refType=instrument, refId=valueCanonical) regardless of method.

Recording the decision

After including (or referencing) an instrument, append to decisions.md:

2026-05-12 — Included PHQ-9 inline. Public domain in this jurisdiction. Source: USPSTF https://www.uspreventiveservicestaskforce.org/.../phq-9.

Pitfalls

• Modifying the wording of a copyrighted instrument and shipping the modification ("just simplifying it"). Don't.
• Inlining an instrument without recording the decision — when the user re-asks "where did this come from?" later, the conversation log may have been compacted away.
• Mixing instrument items with locally-authored items in the same group. Keep them in their own group with a display-typed attribution header.