vigilcare-clinical/docs/clinical-testing-guide.md

VigilCare Clinical Testing Guide

For doctors and nurses evaluating the alerting dashboard

This guide walks you through testing the VigilCare monitoring dashboard. You will review simulated patient scenarios, decide whether alerts are clinically meaningful, and record structured feedback that helps the team improve the system.

No programming knowledge is required. Log in to the dashboard, open Simulation, and start a testing session — the ward populates itself.

---

Table of Contents

1. What you are testing
2. Important notes before you start
3. Getting to the dashboard
4. Tour of the application
5. Your core task — review and rate alerts
6. Understanding the six feedback ratings
7. Recommended testing sessions
8. Scenario scripts
9. Session checklist
10. Submitting your feedback
11. Frequently asked questions
12. New dashboard features
13. Running your own simulation

---

1. What you are testing

VigilCare is a clinical decision support prototype. It watches vital signs and lab-style observations for hospitalized patients and raises alerts when something looks wrong — for example:

• A single vital sign in a warning range (heart rate, blood pressure, temperature)
• A NEWS2 early warning score crossing medium or high risk
• SIRS / sepsis or qSOFA patterns suggesting infection or organ dysfunction
• Rapid deterioration — a vital changing quickly even if still “in range”
• Sepsis bundle tracking — whether time-critical treatments were ordered and completed

The dashboard is where you, as a clinician, would see those alerts and decide what to do. This testing round adds structured feedback: after reviewing each alert, you tell us whether it would help or hinder real clinical work. The dashboard also includes a department overview for unit-level situational awareness, a sepsis bundle board tracking compliance deadlines in real time, critical alert notifications (audible + browser), shift handoff reports in SBAR format, and a vitals entry form for recording observations at the bedside.

Your ratings are the primary output of this study. There are no right or wrong answers — we want your honest clinical judgment on simulated cases.

---

2. Important notes before you start

Simulated patients only

All patients in this test are fictional. Data is generated by the in-app simulation runner, not from real bedside monitors. Treat it like a training exercise, not live clinical work.

While simulation mode is on, a SIMULATION MODE banner appears at the top of the dashboard. Simulated patients also show a SIM badge on the ward. Never assume a SIM patient is a real admission.

Not a production EHR

This dashboard is a research and evaluation tool. It does not replace your hospital’s charting system, does not send real pages, and does not write orders to a live pharmacy or lab.

Acknowledge and resolve are practice actions

You can tap Ack and Resolve on alerts to walk through the workflow. In this environment those actions update the test database only.

Feedback is saved on the server

Your ratings are stored with the alert in the API (and carry which simulation scenario produced the alert when applicable). Export from Alert Quality or Feedback Summary at the end of the session if the study asks for a file copy.

Your login identity

Acknowledging alerts uses your signed-in name and role. Use the nurse or physician account provided for the session.

---

3. Getting to the dashboard

1. Open the dashboard URL provided for your site (often http://localhost:5173 in a local lab).
2. Log in with the nurse or physician account you were given.
3. In the sidebar, open Simulation.
4. On the Sessions tab, pick a recommended session (see §7) and click Start session.

Patients appear on Virtual Ward as the session runs. You do not need a terminal or any command-line tools.

If the ward is empty and you have not started a session yet, go back to Simulation → Sessions. If a previous tester left simulated patients behind, use Reset ward on the Simulation page (see §13).

---

4. Tour of the application

Use the sidebar (desktop) or bottom navigation (mobile) to move between screens. The sidebar includes links to Virtual Ward, Department Overview, Sepsis Bundle Board, Alert Center, and Feedback Summary.

Virtual Ward

Purpose: See who is on the floor and who needs attention first.

• Patients sorted by NEWS2 score by default — click any column header (Room, Patient, NEWS2, qSOFA, Sepsis, Alerts) to re-sort.
• Badge shows count of patients with NEWS2 ≥ 7.
• Search bar — type a patient name or MRN to find someone quickly.
• Quick-filter toggles — narrow the list to Critical (NEWS2 ≥ 7), Has Alerts, or Active Sepsis.
• Filter by department if asked (ICU, General Medicine, Surgery).
• Click a patient row to open their detail page.
• Handoff Report button in the toolbar generates a structured shift handoff for all visible patients (see §12).

What to notice: Does the sort order match how you would prioritize a real ward round? Are the search and filters useful for finding patients quickly?

---

Patient Detail

Purpose: Deep review of one patient — vitals, scores, alerts, trends, and why alerts fired.

Section	What it shows
Scores	Current NEWS2 total and risk level, SOFA score with organ-system breakdown, GCS total and component scores
Latest Vitals	Most recent heart rate, RR, BP, SpO₂, temperature, etc.
Vitals Entry	Record new vital signs manually (7 parameters with AVPU dropdown) — plausibility-validated before submission
Active Alerts	Open alerts for this patient — click a row to see reasoning
Alert reasoning	Plain-language explanation of why the alert fired; may show recent medications
Orders	Clinical orders (labs, antibiotics, fluids, etc.)
Sepsis bundle	If sepsis was suspected — four time-critical elements and compliance status
Vital sign charts	Trends for HR, RR, systolic BP, SpO₂, temperature — with medication administration markers
NEWS2 history	How the early warning score changed over time
SOFA / GCS / qSOFA history	Organ-system breakdown over time, component tracking, evaluation history
Patient banner	Demographics, age, blood type, allergies, emergency contact
Encounter timeline	Merged chronological view of status changes, observation summaries, and alerts
Replay controls	Local timeline bar (pause, speed, Next Alert →) — scrubs charts/vitals to a point in time; does not control the simulator

What to notice: Would you trust these charts and explanations during a real handoff? Is the vitals entry form intuitive? Is anything missing?

---

Alert Center

Purpose: Hospital-wide inbox — all alerts across patients, not just one encounter.

• Tabs: Open, Acknowledged, Resolved, Escalated.
• Each card shows severity, type, details, and time.
• Ack opens a role-aware acknowledgment modal — your name and role are pre-filled from your login, with a preview of the acknowledgment note. Add optional clinical notes before confirming.
• Resolve (must be acknowledged first).
• Critical alert banner — when new critical alerts arrive (detected during polling), a banner appears at the top of the page with an audible tone and browser notification. You can dismiss individual alerts or all at once.
• Feedback buttons on every card (see §5).

What to notice: Is it easy to triage multiple patients from one screen? Is the critical alert notification helpful or distracting? Would you use this during a shift?

---

Department Overview

Purpose: Bird's-eye view of all departments — which units are busiest and which need attention.

• Summary cards show total active patients, critical count (NEWS2 ≥ 7), open alerts, and active sepsis bundles across the hospital.
• One card per department with patient count, acuity distribution bar, alert count, and bundle count.
• Click a department card to jump to the Virtual Ward filtered to that unit.
• Polls every 10 seconds for live updates.

What to notice: Would this view help a charge nurse or bed manager allocate resources? Does the acuity breakdown feel clinically useful?

---

Sepsis Bundle Board

Purpose: Track all active sepsis bundles hospital-wide with countdown timers to the 1-hour compliance deadline.

• Each bundle row shows patient name/MRN, room, department, recognition time, countdown timer, compliance status, and element progress (how many of the four treatment elements are complete).
• Bundles are sorted by urgency: overdue (past deadline, red) → at risk (< 15 minutes remaining, amber) → on track (green).
• Countdown updates every second.
• Summary line shows total bundles and breakdown by urgency category.

What to notice: Is the urgency sorting intuitive? Would real-time countdown timers help your team meet sepsis compliance targets?

---

Feedback Summary

Purpose: Aggregate view of all ratings you (and others on the same browser) have submitted.

• Total ratings, % useful / would act, % false positive, timing issues.
• Breakdown by alert type (e.g. sepsis, NEWS2, heart rate warning).
• Recent feedback list with your notes.
• Export JSON and Export CSV — use CSV for spreadsheets.

Open this at the end of a session to sanity-check your work before export.

---

5. Your core task — review and rate alerts

For each alert you review, complete this short workflow:

1. Read the alert (severity, type, details, time)
2. Optional: open Patient Detail → click the alert → read "why it fired"
3. Optional: look at vitals, charts, medications, sepsis bundle
4. Choose ONE feedback rating (required for that alert)
5. Optional: tap "+ Note" and add a short clinical comment
6. Move to the next alert

Where feedback buttons appear

• Alert Center — below each alert card.
• Patient Detail — below the alert reasoning panel (after you click an alert).
• Active Alerts list — on expanded reasoning view when integrated.

You can rate alerts in any status (Open, Acknowledged, Resolved, Escalated). You may change your rating by selecting a different button — the latest choice replaces the previous one.

Tips for consistent ratings

• Rate based on what you knew at the time the alert fired, using the charts and reasoning as context — not hindsight after the full scenario finished.
• If an alert was technically correct but not actionable, consider Too early, Too late, or Missing context rather than Useful.
• If the patient was stable and the alert reflected expected treatment (e.g. beta-blocker bradycardia), False positive or Missing context may fit better than Useful.
• Use Would act when you would genuinely change management based on that notification alone.

---

6. Understanding the six feedback ratings

Button	When to use it	Example
Useful	Clinically appropriate alert; right concern at right time	NEWS2 rises to 6 as RR and HR worsen in sepsis scenario
Would act	You would change assessment, monitoring, or treatment because of this alert	qSOFA alert on a patient you would escalate to senior review
Too early	Directionally right but fired before you would act	Warning HR while patient still asymptomatic and trending stable
Too late	Real problem existed but alert came after you would have intervened	Deterioration alert after you would already have called a rapid response
False positive	Alert should not have fired for this patient context	Bradycardia warning on a patient on scheduled metoprolol with baseline low HR
Missing context	Alert may be valid but message lacks information you need	HR warning without noting recent beta-blocker dose

Optional notes — what to write

Short phrases are enough. Examples:

• "Expected bradycardia — patient on metoprolol 25 mg PO"
• "Would have acted on NEWS2 ≥ 7 sooner if bundle status visible"
• "Useful but duplicate of HR warning 10 min earlier"
• "Needed lactate trend, not just single value"

---

7. Recommended testing sessions

Session A — Quick orientation (20–30 minutes)

Goal: Learn the UI and rate at least 5 alerts.

1. Open Simulation → Sessions and start Session A — Quick orientation.
2. Watch Virtual Ward as the two patients appear (stable baseline, then UTI/sepsis).
3. Virtual Ward → open a patient → review 2–3 alerts with reasoning + charts.
4. Alert Center → rate remaining alerts.
5. Feedback Summary or Alert Quality → export CSV.

Session B — Alert quality deep dive (45–60 minutes)

Goal: Compare alert types across contrasting scenarios.

1. Open Simulation → Sessions and start Session B — Alert quality deep dive.
2. Rate alerts across the three patients; note differences between false-alarm and sepsis cases.
3. Open Alert Quality → filter by scenario (e.g. medication-false-alarm-01 vs uti-sepsis-elderly-01).
4. Export CSV — scenarioId / sessionId columns attribute each rating.

Session C — Ward workflow (30 minutes)

Goal: Test prioritization and handoff usability on a full ward.

1. Open Simulation → Sessions and start Session C — Ward workflow (seven concurrent patients at high speed).
2. Stay on Virtual Ward — note sort order as new patients appear.
3. Try sorting by different columns (qSOFA, Alerts, Sepsis) — which view is most useful?
4. Use the search bar and quick filters to narrow the list.
5. Round on each high-NEWS2 patient — detail page only, no Alert Center until end.
6. Generate a Handoff Report and review the SBAR content for each patient.
7. Document: Would this order match your morning ward round? Is the handoff report format useful?

Session D — New features deep dive (30–45 minutes)

Goal: Evaluate the new dashboard features for clinical usefulness.

1. Open Simulation → Sessions and start Session D — New features.
2. Open Department Overview — review the unit-level cards and summary stats.
3. Open Sepsis Bundle Board — watch countdown timers and urgency sorting.
4. Return to Virtual Ward — test the search bar, quick filters, and column sorting.
5. Open a patient → use the Vitals Entry form to record manual observations.
6. Wait for a critical alert → note the critical alert banner, sound, and browser notification.
7. Acknowledge an alert using the role-aware modal — review the note preview.
8. Generate a Handoff Report and review the SBAR format.
9. Document: Which new features would you use on a real ward? Which need improvement?

---

8. Scenario scripts

Reference only — the clinical stories behind each scenario file. You start these from Simulation → Sessions (or Scenarios for a single file); you do not need to run commands.

Scenario	Clinical story	What to evaluate
stable-baseline-01.json	Stable inpatient, minimal abnormal vitals	Alert noise — should few or no alerts fire?
medication-false-alarm-01.json	Beta-blocker, baseline low HR, boundary vitals	False alarms, alert fatigue, medication context in reasoning
uti-sepsis-elderly-01.json	Elderly UTI progressing to sepsis	SIRS/qSOFA, NEWS2 trend, sepsis bundle, usefulness of escalation
respiratory-failure-asthma-01.json	Asthma exacerbation	RR/SpO₂ warnings, NEWS2, rapid deterioration
post-op-hemorrhage-01.json	Post-operative bleeding	BP/HR trends, critical vs warning timing
cardiac-arrest-post-mi-01.json	Post-MI deterioration	High-acuity alerts, would-act vs too-late
dka-electrolyte-01.json	Metabolic emergency	Multi-parameter scoring, order visibility
hypothermia-elderly-01.json	Temperature-driven risk	Temp warnings, NEWS2 contribution

Replay speed is chosen on the Simulation page (Real time / Fast / Very fast / Instant). Session presets also carry a default speed you can override before starting.

---

9. Session checklist

Use this during or after your session.

Virtual Ward

• Patient list loads and refreshes
• NEWS2 sort order feels clinically sensible
• Clicking column headers (Room, Patient, NEWS2, qSOFA, Sepsis, Alerts) changes sort order
• Patient search by name or MRN works
• Quick filters (Critical, Has Alerts, Active Sepsis) narrow the list correctly
• Department filter works (if tested)
• Patient detail opens from row click
• Handoff Report generates and displays correctly (test print/PDF if possible)

Patient Detail

• Latest vitals match what you expect for the scenario
• NEWS2 score and risk level display correctly
• SOFA score with organ-system breakdown visible
• GCS score with component breakdown visible
• Vitals Entry form validates values and submits successfully
• Clicking an alert shows reasoning panel
• Medication context appears when relevant (beta-blocker scenario)
• Vital sign charts show sensible trends (with medication markers where applicable)
• NEWS2 history chart updates over time
• SOFA / GCS / qSOFA history charts update over time
• Patient banner shows demographics, allergies, emergency contact
• Encounter timeline shows chronological events
• Sepsis bundle panel appears when sepsis alerts fire
• Next Alert → selects each open alert, scrubs charts to that time, and scrolls the review section into view

Alert Center

• Open / Acknowledged / Resolved tabs filter correctly
• Acknowledge modal shows your name and role, note preview works
• Acknowledge and resolve workflow understandable
• Critical alert banner appears for new critical alerts (with sound if not muted)
• Feedback buttons visible on every card

Department Overview

• Summary cards show total patients, critical count, alerts, bundles
• Department cards load with acuity bars
• Clicking a department navigates to ward filtered by that unit

Sepsis Bundle Board

• Active bundles listed with countdown timers
• Urgency sorting (overdue → at risk → on track) feels correct
• Countdown timer updates in real time

Feedback (Phase 19)

• Rated at least 5 alerts (more is better)
• Used more than one rating category (not all “Useful”)
• Added notes on at least 2 alerts where context mattered
• Changed a rating intentionally — confirm new selection sticks after refresh
• Feedback Summary totals look correct
• Exported CSV (and JSON if requested)

Overall clinical judgment

• Which alert types were most trustworthy?
• Which caused unnecessary noise?
• What information was missing from alert text or reasoning?
• Was the department overview useful for situational awareness?
• Was the sepsis bundle board useful for compliance tracking?
• Was the handoff report format (SBAR) clinically appropriate?
• Were critical alert notifications helpful or disruptive?
• Would you want this on a real ward? Why or why not?

---

10. Submitting your feedback

At the end of your session:

1. Open Alert Quality (or Feedback Summary) from the sidebar.
2. Review totals and, if simulation was used, the By Scenario breakdown.
3. Click Export CSV.
4. Save the file (e.g. vigilcare-feedback-dr-smith-2026-06-20.csv).
5. Send to the study contact via the method they specify (email, shared drive, study portal).

The CSV includes alert ID, alert type, your rating, notes, timestamp, and — when simulation mode is enabled — scenarioId and sessionId so ratings can be compared across scenarios (especially useful for Session B).

Same computer: Ratings are stored on the server for your account. Different computer: Export before switching devices if you need a local copy.

---

11. Frequently asked questions

I don’t see any patients.
Open Simulation → Sessions and start a session (or an individual scenario on the Scenarios tab). If a previous tester left the ward empty after a reset, start Session A for a quick two-patient setup.

How do I clear the ward for the next person?
On Simulation, use Reset ward. Confirm by typing RESET. This deletes only simulated patients and their alerts/feedback — never real patients. Stop any active runs first (or use Stop all runs).

What does the SIM badge mean?
The patient was created by a simulation session or scenario replay. The amber SIMULATION MODE banner means the environment is allowed to create those patients. Treat SIM patients as training data only.

Charts are empty but vitals show data.
Wait a few seconds — the page polls every 5 seconds. If charts stay empty, refresh the patient page or tell the study contact.

Can I rate the same alert twice?
You can change your rating; only the latest is kept per alert per user.

Do I have to acknowledge before rating?
No. Rate any alert in any status.

What’s the difference between Useful and Would act?
Useful = good alert clinically. Would act = you would specifically change care because of it. An alert can be useful information but not change your plan — use the button that best matches your reasoning.

The replay bar doesn’t pause the simulator.
Correct — replay controls scrub observation/chart data already loaded in the browser (pause, speed, and Next Alert → move a local timeline). Session and scenario speed are set on the Simulation page before you start.

The alert sound is annoying — can I turn it off?
Yes. Click the sound toggle icon in the header bar to mute critical alert tones. The visual banner and browser notifications still appear.

How do I print the handoff report?
Open the Handoff Report from the Virtual Ward toolbar, then click Print / Save PDF. The report is formatted for printing — the overlay and controls are hidden in print view.

Can I record vitals from the dashboard?
Yes. On any Patient Detail page, use the Vitals Entry section to enter vital signs. Values are validated before submission and processed by the same scoring engines as device data.

What is the Sepsis Bundle Board?
A hospital-wide view of all active sepsis bundles with live countdown timers. It helps track whether the four required treatment elements (blood cultures, lactate, antibiotics, fluids) are completed within the 1-hour compliance window.

Dark mode?
Toggle in the header if your eyes prefer it; all screens support dark mode.

Who do I contact with problems?
Speak to your session contact. Technical issues (blank screen, errors) may need the API or dashboard restarted by whoever hosts the environment.

---

Quick reference card

I want to…	Go to…
See all patients by acuity	Virtual Ward
Find a specific patient	Virtual Ward → search bar (name or MRN)
See only critical patients	Virtual Ward → Critical quick-filter toggle
Deep-dive one patient	Click patient → Patient Detail
Record vital signs manually	Patient Detail → Vitals Entry form
See all departments at a glance	Department Overview (sidebar)
Track sepsis bundle compliance	Sepsis Bundle Board (sidebar)
Triage all hospital alerts	Alert Center
Understand why an alert fired	Patient Detail → click alert → Reasoning
Acknowledge an alert	Alert Center or Patient Detail → Ack button → modal
Rate an alert	Feedback buttons under alert card or reasoning
See ratings by scenario	Alert Quality → scenario filter / By Scenario
See my ratings aggregate	Feedback Summary or Alert Quality
Generate a shift handoff	Virtual Ward → Handoff Report button
Start a testing session	Simulation → Sessions
Clear simulated patients	Simulation → Reset ward
Submit results	Alert Quality or Feedback Summary → Export CSV

---

12. New dashboard features

This section summarizes features added after the initial dashboard release. If you are already familiar with the basic workflow (ward → patient detail → alerts → feedback), read this section for what is new.

Sortable ward table

The ward table now supports column sorting. Click any column header (Room, Patient, Department, NEWS2, qSOFA, Sepsis, Alerts) to sort by that column. Click again to reverse direction. The default remains NEWS2 descending (most acute first). A secondary sort by NEWS2 breaks ties when sorting by other columns.

Patient search and quick filters

A search bar at the top of the ward lets you type a patient name or MRN to find someone instantly. Three quick-filter toggles narrow the list:

• Critical — only patients with NEWS2 ≥ 7
• Has Alerts — only patients with open alerts
• Active Sepsis — only patients with an active sepsis bundle or SOFA_SEPSIS alert

A "Clear filters" button resets all filters and search.

Department Overview (/departments)

A new Department Overview page (accessible from the sidebar) provides a bird's-eye view of the hospital. Summary cards at the top show total active patients, critical count, open alerts, and active sepsis bundles. Below, one card per department shows its patient count, acuity distribution (a visual bar), and alert/bundle counts. Click a department card to navigate to the ward filtered to that unit.

Sepsis Bundle Board (/sepsis)

A new Sepsis Bundle Board page tracks all active sepsis bundles hospital-wide. Each bundle row shows the patient, room, department, recognition time, a live countdown timer to the 1-hour compliance deadline, and element completion progress. Bundles are color-coded and sorted by urgency: overdue (past deadline) → at risk (< 15 minutes remaining) → on track. The countdown updates every second.

Critical alert notifications

When the dashboard detects new critical alerts during its polling cycle, a critical alert banner appears at the top of the page. It includes:

• An audible two-tone alert (can be muted via the sound toggle in the header)
• A flashing browser title (⚠ CRITICAL ALERT — VigilCare)
• A browser notification (if you grant notification permission when prompted)

Dismiss individual alerts or all at once. The banner does not replace the Alert Center — it highlights new critical arrivals so you do not miss them.

Shift handoff report

The Handoff Report button on the Virtual Ward toolbar generates a structured shift handoff document for all visible patients (respecting any active filters). The report includes:

• Ward summary — department, patient count, critical count, open alerts, active bundles
• Per-patient SBAR — Situation (admission reason), Background (allergies), Assessment (scores + latest vitals + open alerts), Recommendation (pending orders + sepsis bundle status)
• Scores overview — NEWS2, SOFA (with delta), GCS, qSOFA per patient

Use Print / Save PDF to export the report for paper handoff or archive.

Vitals entry form

On the Patient Detail page, a Vitals Entry section lets you manually record observations for seven vital parameters: Heart Rate, Respiratory Rate, Systolic BP, Diastolic BP, SpO₂, Temperature, and AVPU (as a dropdown). Values are validated against plausibility ranges before submission. At least one vital sign must be entered. This simulates bedside manual charting — observations posted through this form are processed by the same scoring engines as device-generated data.

Role-aware alert acknowledgment

The Ack button now opens a modal that shows:

• Your name and role (from your login session)
• Role-specific guidance (e.g. "You are acknowledging as a nurse — documenting awareness of this alert")
• A preview of the acknowledgment note that will be recorded
• An optional text field for additional clinical notes

This makes the acknowledgment workflow more realistic and tracks who acknowledged what.

---

13. Running your own simulation

You can drive the entire evaluation from the dashboard — no terminal required.

Session presets

Simulation → Sessions lists the recommended packs (A–D) with goals and estimated duration. Start session launches every scenario in the preset, staggered so the ward fills smoothly. Capacity is checked up front: if there are not enough free run slots, the Start button stays disabled with an explanation.

Individual scenarios

Simulation → Scenarios is the full catalogue. Search and tag filters help you find a single case (e.g. a MIMIC-generated stay). Use this when you want one patient at a time rather than a full session.

Speed

Choose Real time, Fast, Very fast, or Instant before starting. Session starts use this speed (overriding the preset default). Faster speeds are better for ward-round sessions; slower speeds help when you want to watch alerts arrive one by one.

Reset

Reset ward removes all simulated patients, their observations, alerts, and feedback. Type RESET to confirm. Non-simulated patients are never deleted. Reset is blocked while runs are still active — use Stop all runs first.

After a reset, Virtual Ward and Alert Center should be empty of simulated data. Start Session A (or another preset) for the next tester.

---

Thank you for participating. Your clinical feedback directly shapes whether VigilCare alerts help or harm real ward workflows.