guideline-search

name	guideline-search
description	Find clinical practice guidelines from authoritative bodies (NICE, USPSTF, ACP, AHRQ, GIN). Use when the user asks "what does the guideline say" or wants to anchor a question or threshold to a recommended practice. Produces guideline-typed citations with the canonical URL of the recommendation.

Guideline search

When to use this

• The user wants the question to reflect current standard of care.
• You're choosing a threshold (e.g. PHQ-9 cutoff, BP target, LDL goal) and need authority for the number you pick.
• You're proposing a red-flag screen and want the canonical list.

Sources, in priority order

1. NICE (UK) — https://www.nice.org.uk/guidance/<id>. Use site search; or query https://www.nice.org.uk/api/v1/guidance.
2. USPSTF — https://www.uspreventiveservicestaskforce.org/. Letter-graded recommendations.
3. ACP/AHA/ESC — society guidelines, usually on the society site.
4. AHRQ — https://www.ahrq.gov/ evidence reports; especially useful for screening instruments.
5. GIN (Guidelines International Network) library when nothing else surfaces a recent recommendation.

For each candidate, capture: title, issuing body, year, version, canonical URL, and (if relevant) the recommendation strength / quality of evidence.

Output

Write the organized source record to $FORMTASTIC_RUN_DIR/output/research/bundle.json. Capture each selected guideline in sources[] with { id, kind: "guideline", title, url, publisher, year?, citation?, relevance, evidenceLevel?, sourceFile, extractFile? }; capture the site/API query in searches[] with transcriptFile; capture concise extraction notes in notes[] with noteFile.

Also write supporting files under output/research/searches/, output/research/sources/, output/research/extracts/, and output/research/notes/ using ids that match bundle.json. Then write output/findings.json as the compact UI-facing takeaway, and propose a guideline-typed citation in the questionnaire only when the guideline directly supports a specific item:

{
  "url": "https://formtastic.studio/fhir/StructureDefinition/citation",
  "extension": [
    { "url": "refType", "valueCode": "guideline" },
    { "url": "refId",   "valueCanonical": "<canonical URL of the guideline>" },
    { "url": "note",    "valueMarkdown": "Recommendation X.Y, grade A." }
  ]
}

Use valueCanonical for guidelines (they have stable canonical URLs); use valueUri only for papers.

Pitfalls

• Anchoring to a withdrawn or superseded guideline. Always check the guideline status / date.
• Mixing NICE recommendation grades and USPSTF letter grades; they are NOT comparable. Cite both with their native grading.
• "Standard of care" claims without a specific guideline. If you can't find one, say so.