LoopGuard Passport - Judge Reproduction Guide

Copy-paste prompts, BYO agent setup, demo-mode and live-FHIR flows, and claim boundaries for Prompt Opinion judges.

1. What Judges Should Understand First

What LoopGuard Does

LoopGuard reads patient-scoped FHIR context, detects open diagnostic follow-up loops, suppresses completed work, ranks urgency, enriches loops with HPO phenotypes, and creates review-required coordination artifacts.

What It Does Not Do

LoopGuard does not diagnose, prescribe, order, schedule procedures, or contact patients. All outputs are draft-only and require responsible clinician review.

Why Prompt Opinion Matters

Prompt Opinion supplies the patient-scoped FHIR context and MCP workspace. The LoopGuard MCP server supplies deterministic evidence and the visual Passport dashboard.

2. Demo Mode vs Live FHIR Mode

Mode Use When What It Reads Judge Expectation
demo_mode=true Fast, deterministic judging path with no credentials. Bundled synthetic Maria Lopez demo data inside the MCP server. Always reproducible. No live FHIR patient selection required.
demo_mode=false Live Prompt Opinion patient context is selected and FHIR headers are available. Current Prompt Opinion patient-scoped FHIR resources. Shows data_mode: prompt_opinion_fhir_context when headers/scopes work.
cohort_scan demo_mode=true Optional panel-style demonstration. Bundled synthetic patients inside the LoopGuard MCP server. Does not scan the live Prompt Opinion workspace.
Cohort scan claim boundary: The cohort scan is a synthetic panel demo using locally bundled patients in the MCP server. It does not enumerate real Prompt Opinion patients or scan a live FHIR workspace. A production live panel scan would require broader patient-list scopes, pagination, rate limits, and safety controls.

3. Maria Lopez Patient Bundle Details

This is the synthetic patient represented by scripts/loopguard_test_patient.json. Judges can import that bundle into Prompt Opinion, select the uploaded patient, and use the details below to understand exactly why LoopGuard finds the RED FIT-to-colonoscopy loop, the pulmonary nodule follow-up loop, the diabetes recheck context, and the suppressed completed potassium loop.

FHIR Resource Patient Detail Why It Matters in the Demo
Patient Maria Lopez, female, birthDate 1968-05-15 Selected/uploaded synthetic patient shown in Prompt Opinion Patient Details. If the workspace display name appears as LoopGuard Patient, the birth date and clinical bundle still identify the same synthetic patient.
Observation Hemoglobin 9.2 g/dL, LOW, LOINC 718-7 Supports anemia phenotype and care-continuity risk.
Observation Ferritin 7 ng/mL, LOW, LOINC 2276-4 Supports iron-deficiency anemia phenotype.
Observation Positive fecal immunochemical test / positive FIT, value Positive Creates the high-priority FIT-to-colonoscopy follow-up loop.
Condition Iron-deficiency anemia, Type 2 diabetes mellitus, Unintentional weight loss Provides HPO context and compound phenotype risk.
ServiceRequest GI referral to gastroenterology for colonoscopy follow-up positive FIT, authored 2025-10-12 Shows the intended care loop that remains open until follow-up is completed.
DiagnosticReport CT chest: 6mm right lower lobe pulmonary nodule; repeat CT in 6-12 months Creates the pulmonary nodule follow-up loop.
DocumentReference Office visit note documenting hemoglobin 9.2, ferritin 7, positive FIT, GI evaluation, colonoscopy follow-up, and recheck hemoglobin Demonstrates implicit loop detection from clinical narrative.
DocumentReference Radiology report documenting pulmonary nodule follow-up recommendation Demonstrates narrative follow-up extraction from diagnostic reports.
Task Completed potassium follow-up; repeat potassium normal; resolved Demonstrates completed-loop suppression so resolved work is not re-alerted.
Condensed Patient Bundle Details
Patient: Maria Lopez, female, DOB 1968-05-15.
Observations: hemoglobin 9.2 g/dL LOW; ferritin 7 ng/mL LOW; positive FIT.
Conditions: iron-deficiency anemia; type 2 diabetes mellitus; unintentional weight loss.
ServiceRequest: GI referral to gastroenterology for colonoscopy follow-up after positive FIT, authored 2025-10-12.
DiagnosticReport: CT chest with 6mm right lower lobe pulmonary nodule; repeat CT chest in 6-12 months.
DocumentReferences: office visit note and CT chest report with narrative follow-up commitments.
Completed Task: abnormal potassium follow-up resolved; repeat potassium normal.
Expected LoopGuard result: positive FIT to colonoscopy is RED; pulmonary nodule CT is YELLOW; diabetes A1C context is YELLOW/LOW; potassium follow-up is suppressed as completed.

4. MCP Tool Map

Tool Why It Exists What Judges Should Look For
loopguard.debug_fhir_query_patterns Checks whether Prompt Opinion is passing FHIR headers and whether patient-scoped queries work. Header presence, redaction status, no token exposure.
loopguard.analyze_patient_loops Main deterministic pipeline: loop detection, suppression, HPO enrichment, guideline urgency, compound synthesis, FHIR artifact draft. review_required: true, open loops, suppressed loops, ESCALATE_TODAY, HPO flags.
loopguard.open_passport_app Visual MCP App dashboard for the same evidence, with safe draft coordination fields. RED/YELLOW loop cards, edit fields, Save Draft button.
SaveLoopDraftEdit Internal MCP App action that persists a safe draft edit. FHIR Task, DocumentReference, and Provenance/audit context when supported.
loopguard.cohort_scan Optional synthetic panel triage demo. Maria ranked first in a bundled synthetic escalation queue.

5. BYO Agent Configuration

Use this system prompt when creating or judging a BYO Prompt Opinion agent connected to the LoopGuard MCP server.

LoopGuard MCP Server URL
https://loopguard-passport.onrender.com/mcp
Optional consultation instructions: leave this field blank/default for this submission. LoopGuard is judged as a BYO Prompt Opinion agent connected to an MCP server; the important configuration is the system prompt below.
BYO Agent System Prompt
You are LoopGuard Passport Assistant, a governed care-continuity agent inside Prompt Opinion.

Your job is to help clinicians review unresolved follow-up loops using LoopGuard MCP tool evidence, then generate your own clinical care-coordination synthesis. LoopGuard MCP is the deterministic evidence engine. You are the generative reasoning layer.

Available tools:
- loopguard.analyze_patient_loops: returns structured JSON evidence for patient-scoped loop analysis.
- loopguard.open_passport_app: opens the visual Passport dashboard.
- loopguard.debug_fhir_query_patterns: validates live Prompt Opinion FHIR context when needed.
- loopguard.cohort_scan: use only if exposed and the user asks for a synthetic panel scan.

Tool-use rules:
- For any patient-specific loop, risk, passport, FHIR artifact, or follow-up question, call loopguard.analyze_patient_loops before answering.
- Use demo_mode=false when Prompt Opinion patient FHIR context is available.
- Use demo_mode=true only when the user asks for the synthetic demo or no live patient context exists.
- Use open_passport_app when the user asks for a visual dashboard, Passport UI, editable passport, or app view.
- Always report data_mode and review_required from the tool output.

Generative AI Factor requirement:
Every time you receive LoopGuard tool output with open_loops or compound_risk, you MUST write a fresh 2-3 sentence "Agent-generated synthesis" from the raw evidence fields. Base it on open_loops[*].urgency, open_loops[*].temporal.temporal_zone, days_open, days_over_guideline, guideline_source, hpo_flags, patient_summary.conditions, notification_gaps, open_loop_count, suppressed_loop_count, and missing_information.
Do NOT copy, quote, paraphrase, or lightly rewrite compound_risk.synthesis_rationale, compound_risk.key_pattern, compound_risk.escalation_recommendation, or compound_risk.evidence_boundaries. You may report compound_risk.compound_risk_level as the deterministic score, but your narrative must be independently generated from the raw evidence.

Evidence fidelity:
- When presenting tool fields, preserve exact loop_id, temporal.guideline_source, temporal.temporal_zone, temporal.days_open, temporal.days_over_guideline, hpo_flags.term, compound_phenotype_risk, data_mode, and review_required values from the tool output.
- Do not rename, shorten, normalize, or prettify loop IDs, guideline names, HPO terms, temporal zones, or FHIR artifact names.
- Use "high-priority RED-zone follow-up" rather than "critical" unless the tool urgency is exactly "critical."
- Use "responsible clinician review" rather than "clinical intervention."
- In the agent-generated synthesis and evidence-boundary section, do not use external outcome claims unless they appear in raw open_loop evidence or the user asks for literature. Prefer guideline timing, missing information, HPO phenotype evidence, and care-coordination burden.
- Evidence-boundary section must NOT mention external literature, adverse outcomes, cancer outcomes, Corley/JAMA, or positive-FIT outcome associations unless the user explicitly asks for literature. For normal LoopGuard reviews, evidence boundaries must only state: draft/advisory status, clinician review required, no diagnosis, no prescribing, no orders, no scheduling, no patient contact, and uncertainty/missing-information limits.

Clinical safety:
- Never diagnose.
- Never prescribe.
- Never place orders.
- Never schedule procedures.
- Never contact patients.
- Never imply an action has already occurred.
- Never claim diabetes independently increases cancer risk from delayed colonoscopy.
- Use diabetes only as care-coordination context unless the supplied evidence explicitly supports more.
- All outputs are draft, advisory, and require responsible clinician review.
- If open_loop_count is 0, do not say "no further action needed." Say no LoopGuard-detected open loops were found in available data and clinician review remains required.
- If evidence is missing or ambiguous, state the uncertainty.

Style:
Use concise clinical language. Lead with the compound risk level, review_required, data_mode, and your agent-generated synthesis. Then present a clean table of loops. Ground every risk statement in supplied evidence, temporal zones, HPO terms, guideline names, missing information, or FHIR artifact status.

6. Exact Judge Prompts

A. Live FHIR Diagnostic

Why this exists: Shows Prompt Opinion is passing patient-scoped FHIR context safely, without exposing tokens.

Prompt
Call loopguard.debug_fhir_query_patterns for the current Prompt Opinion patient context. Summarize header presence, query status, and redaction status. Do not print any access token.

B. Synthetic Maria Analysis

Why this exists: Reproducible first-pass judge path. No credentials, live FHIR headers, or workspace patient selection required.

Prompt
Call loopguard.analyze_patient_loops with demo_mode=true. Return data_mode, review_required, open loop count, suppressed loop count, compound risk level, top loop zone, HPO phenotype flags, and a concise synthesis from raw evidence. Do not expose tokens or FHIR headers.

C. Live FHIR Maria Analysis

Why this exists: Demonstrates selected Prompt Opinion patient-scoped FHIR reads when the synthetic Maria patient has been uploaded into the workspace.

Prompt
Call loopguard.analyze_patient_loops with demo_mode=false for the current Prompt Opinion patient. Return data_mode, review_required, open loop count, suppressed loop count, compound risk level, top loop zone, HPO phenotype flags, and a concise synthesis from raw evidence. Do not expose tokens or FHIR headers.

D. Open Synthetic Passport Dashboard

Why this exists: Opens the MCP App UI for the bundled demo patient.

Prompt
Call loopguard.open_passport_app with demo_mode=true.

E. Open Live Passport Dashboard

Why this exists: Opens the MCP App UI for the selected Prompt Opinion patient when FHIR context is available.

Prompt
Call loopguard.open_passport_app with demo_mode=false for the current Prompt Opinion patient.

F. HPO Phenotype Flags Follow-Up

Why this exists: Gives judges a clean way to inspect the phenotype evidence if the chat answer is too short.

Prompt
Show the HPO phenotype flags for the top open loop from the last LoopGuard analysis, including code, label, and evidence source.

G. Optional Synthetic Cohort Scan

Why this exists: Demonstrates panel-style prioritization while staying honest that this is not a live workspace scan.

Prompt
Call loopguard.cohort_scan with demo_mode=true. Summarize total_patients, patients_with_red_loops, total_open_loops, escalation_queue, review_required, and safety_note. State clearly that this cohort scan uses bundled synthetic patients inside the MCP server and does not scan the live Prompt Opinion workspace.

H. Dashboard Edit Text

Why this exists: Shows safe coordination-only editing before FHIR write-back.

Text to Enter in Draft Next Action
Expedite GI referral and confirm colonoscopy scheduling.

7. Fallback Tool Names

If Prompt Opinion exposes flat aliases instead of dotted names, use these prompts.

Fallback Analysis
Call analyze_patient_loops with demo_mode=true.
Fallback Dashboard
Call open_passport_app with demo_mode=true.
Fallback Cohort
Call cohort_scan with demo_mode=true.

8. Video Walkthrough Checklist

  1. Show title: LoopGuard Passport - Governed Clinical Loop Closure.
  2. Run live FHIR diagnostic only if recording live context; otherwise skip to demo analysis.
  3. Run loopguard.analyze_patient_loops and show ESCALATE_TODAY, review_required: true, open loops, suppressed loop, and HPO flags.
  4. Open loopguard.open_passport_app and show the visual Passport dashboard.
  5. Edit only a safe coordination field, such as draft next action.
  6. Click Save Draft and show Task/DocumentReference evidence in Patient Details if available.
  7. Optionally run synthetic cohort scan and state the demo-mode caveat.
  8. Close with the one-line safety story.

9. Expected Evidence to Point Out

Evidence Expected Value Why It Matters
Compound risk ESCALATE_TODAY Shows LoopGuard prioritizes urgent silent follow-up failures.
Review flag review_required: true Shows human-in-the-loop safety.
Top loop Positive FIT to colonoscopy, RED, 200 days open Shows guideline-grounded temporal urgency.
Suppressed loop Completed potassium follow-up Shows closed work is not re-alerted.
HPO flags HP:0001903, HP:0001824, HP:0034307 Shows phenotype enrichment and compound risk context.
FHIR write-back Task + DocumentReference, Provenance/audit context when supported Shows governed persistence into the patient record.

10. Troubleshooting

Symptom Likely Cause Fix
demo_mode=false fails FHIR headers/scopes or current patient context are unavailable. Run debug prompt first, select the patient, verify scopes, or use demo_mode=true.
Dashboard does not open The agent called JSON analysis instead of the MCP App tool. Use loopguard.open_passport_app, not loopguard.analyze_patient_loops.
Cohort scan not available Optional cohort tool is disabled. Enable LOOPGUARD_ENABLE_COHORT_TOOL=true before server registration, or skip cohort in judging.
Tool output is too verbose Prompt asked for raw JSON. Ask for a concise synthesis and the specific fields listed in this guide.

11. Links

Closing line: LoopGuard does not find problems. It helps prevent the moment a missed cancer begins - the silent follow-up that nobody tracked.