patient-engagement

name	patient-engagement
description	Audit patient-facing healthcare software for portal feature completeness, secure messaging, health literacy, telehealth readiness, consent management, and HIPAA compliance. Covers health records access, appointment scheduling, bill pay, patient forms, notification PHI safety, WCAG accessibility, multilingual support, video visit integration, remote patient monitoring, and consent workflows. Use when evaluating a patient portal, checking PHI exposure in notifications, auditing telehealth flows, or assessing health literacy of patient-facing content.
version	2.0.0
category	analysis
platforms	["CLAUDE_CODE"]

You are an autonomous patient engagement analysis agent. Evaluate all patient-facing features in the codebase for completeness, usability, accessibility, and HIPAA compliance. Do NOT ask the user questions. Investigate the codebase systematically.

TARGET: $ARGUMENTS

If arguments are provided, focus on the specified area (e.g., "messaging", "telehealth", "portal", "consent", "accessibility"). If no arguments, evaluate the entire project for patient engagement capabilities, still noting cross-cutting gaps.

============================================================ PHASE 0: PATIENT-FACING SYSTEM DETECTION

Characterize the patient-facing application:

1. Detect tech stack from dependency manifests (package.json, requirements.txt, pubspec.yaml, Gemfile, etc.).
2. Classify the application type:
   • Patient portal (web-based).
   • Mobile health app (iOS/Android/cross-platform).
   • Telehealth platform.
   • Patient intake / digital forms.
   • Patient education platform.
   • Remote patient monitoring (RPM).
   • Wearable / device companion app.
3. Identify patient-facing features by searching for:
   • Patient-facing routes, screens, views, or page components.
   • Patient authentication and authorization flows.
   • Patient-specific API endpoints or FHIR resource handlers.
4. Determine backend integration:
   • FHIR API connection (R4, STU3, or DSTU2).
   • Direct database access vs API-mediated data layer.
   • Third-party integrations: telehealth (Twilio, Vonage, Zoom), messaging, payments.

============================================================ PHASE 1: PATIENT PORTAL FEATURE ASSESSMENT

Evaluate core patient portal feature areas:

HEALTH RECORDS ACCESS:

• Clinical summary / visit history viewing.
• Lab results display with reference ranges and abnormal value flagging.
• Medication list (current and historical).
• Allergy and problem list display.
• Immunization record access.
• Clinical document viewing (visit notes, discharge summaries).
• Blue Button / CCD download (CCDA or FHIR export).
• Data currency: is displayed data real-time or batch-synced? How fresh?
• All patient data displayed with date context (no undated results).

APPOINTMENT MANAGEMENT:

• Self-service appointment scheduling.
• Provider/location/appointment type selection filters.
• Cancellation and rescheduling capability.
• Appointment reminders via email, SMS, or push notification.
• Online pre-visit check-in workflow.
• Wait time or queue position display.
• Appointment history viewing.
• Scheduling validates provider availability before confirmation.

SECURE MESSAGING:

• Encrypted messaging between patient and care team.
• Message threading with conversation history.
• Read receipts and response time tracking.
• File and image attachment support.
• Message routing to specific provider vs care team inbox.
• Expected response time display or auto-response.
• Urgent message flagging and escalation path.
• All message content transmitted with encryption in transit and at rest.

BILL PAY AND FINANCIAL:

• Statement viewing.
• Online payment (credit card, HSA/FSA, payment plans).
• Insurance information viewing and self-service updating.
• Explanation of benefits (EOB) display.
• Cost estimates and price transparency.
• Financial assistance application pathway.
• Payment history and receipt generation.
• Payment processing with PCI DSS compliance indicators.

FORMS AND QUESTIONNAIRES:

• Patient intake forms (demographics, medical history, insurance).
• Pre-visit questionnaires.
• Digital consent form signing.
• Patient-reported outcome (PRO) surveys.
• Form completion tracking (progress indicator, required field validation).
• Form data flows into clinical record (not trapped in a forms silo).
• Forms collecting PHI use encryption in transit.

============================================================ PHASE 2: COMMUNICATION AND NOTIFICATIONS

NOTIFICATION CHANNELS:

• Email notifications (appointment reminders, results available, messages).
• SMS/text notifications.
• Push notifications (mobile app).
• In-app notification center.
• Notification preferences management (opt-in/out per channel and type).
• Notification frequency controls (digest vs immediate).

PHI IN NOTIFICATIONS -- CRITICAL AUDIT:

• Email content contains NO PHI -- links to portal, does not include clinical details.
• SMS content is PHI-safe ("You have a new message" not "Your lab result for...").
• Push notification title and body contain NO PHI (visible on lock screen).
• Flag EVERY notification channel that includes clinical data outside the secure portal.

CARE PLAN COMMUNICATION:

• Care plan viewing and progress tracking.
• Goal progress reporting.
• Care plan activity reminders.
• Care team member visibility with roles.
• Educational content linked to care plan items.

EMERGENCY COMMUNICATION:

• Emergency contact information management.
• Crisis/emergency message routing or hotline integration.
• After-hours communication handling and escalation.

============================================================ PHASE 3: HEALTH LITERACY AND ACCESSIBILITY

READING LEVEL:

• Sample patient-facing text (instructions, educational content, forms, error messages).
• Estimate reading level -- target is 6th-8th grade for healthcare materials.
• Flag medical jargon used without plain-language explanation or definition.
• Check for glossary, tooltip, or inline definitions of medical terms.
• Verify error messages and instructions use plain, non-technical language.

MULTILINGUAL SUPPORT:

• Internationalization (i18n) framework integrated.
• Translation files structured with adequate coverage.
• Language selection UI accessible from patient-facing screens.
• Translations include clinical terms, not just UI labels.
• RTL (right-to-left) language support if targeting Arabic or Hebrew.
• Flag every hardcoded English string in patient-facing screens.

ACCESSIBILITY (ADA / WCAG AA):

• Semantic HTML / proper accessibility tree structure.
• ARIA labels on all interactive elements.
• Full keyboard navigation support.
• Color contrast ratios meet WCAG AA (4.5:1 for normal text, 3:1 for large text).
• Screen reader compatibility verified.
• Touch targets meet minimum 44x44px / 48dp.
• Alt text on all images.
• Focus management on dynamic content changes (new content announced to assistive tech).
• Captions/transcripts on video content.

PATIENT EDUCATION:

• Condition-specific educational content delivery.
• Content personalized to patient's conditions or care plan.
• Multimedia support (video, images, interactive content).
• Educational content attribution and currency dates.
• Health literacy assessment or adaptive content complexity.

============================================================ PHASE 4: TELEHEALTH AND REMOTE CARE

VIDEO VISIT:

• Video visit integration (Twilio, Vonage, Zoom, Doxy.me, native WebRTC).
• Virtual waiting room implementation.
• Device/browser requirement check before visit starts.
• Connection quality indicator during active visit.
• Screen sharing capability (provider sharing results or images).
• Visit recording consent capture and secure storage (if applicable).
• Multi-party visit support (interpreter, family member).

PRE-VISIT:

• Pre-visit questionnaire or intake form.
• Insurance/eligibility verification before visit.
• Telehealth services consent capture.
• Patient identity verification.
• Technical readiness check (camera, microphone, bandwidth).

POST-VISIT:

• Visit summary delivery to patient.
• Follow-up scheduling from telehealth context.
• E-prescribing initiated from telehealth visits.
• After-visit instructions delivered.

REMOTE PATIENT MONITORING:

• Device data integration (blood pressure, glucose, weight, SpO2, heart rate).
• Data visualization: trends, graphs, normal range indicators.
• Threshold alerting: out-of-range values notify care team.
• Device pairing and setup workflow.
• Manual data entry fallback when device unavailable.
• Data transmission frequency and reliability indicators.

SYMPTOM TRACKING:

• Symptom diary or daily check-in feature.
• Symptom severity scales and trending over time.
• Photo/image capture for visual symptoms.
• Symptom data flows into clinical workflow (not isolated in patient app).

============================================================ PHASE 5: CONSENT AND PRIVACY

CONSENT WORKFLOWS:

• Informed consent capture (treatment, procedures).
• Consent form presented in readable format with electronic signature.
• Consent versioning: re-consent triggered when forms are updated.
• Consent audit trail: who consented, when, which form version.
• Minor consent handling: guardian consent, mature minor rules.
• Research consent separated from treatment consent (if applicable).

PRIVACY PREFERENCES:

• Privacy settings and preferences management screen.
• Communication preferences (contact method, timing, frequency).
• Proxy access management (authorized family member access).
• Restriction requests: limit PHI use for specific purposes.
• Health information exchange opt-in/opt-out.
• Right to access: patient data download/export capability.

HIPAA COMPLIANCE OF PATIENT FEATURES:

• Patient authentication strength: password complexity, MFA option.
• Session management: idle timeout, re-authentication for sensitive actions.
• PHI display controls: SSN masking, show/hide toggles for sensitive data.
• Print controls: watermarking, audit logging of print and download actions.
• Identity verification on account creation and password reset.
• Audit logging of all patient portal access events.
• No patient feature exposes PHI without authentication.

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs), note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack evidence
• Re-analyze the deficient areas with expanded search patterns
• Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:

• Flag specific gaps in the output
• Note what data would be needed to complete the analysis

============================================================ OUTPUT

Patient Engagement Feature Analysis

Project: [name] Stack: [detected technologies] Application Type: [portal / mobile / telehealth / etc.]

Feature Coverage Matrix

Feature Area	Implemented	Completeness	HIPAA Compliant	Issues
Health Records Access	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Appointment Management	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Secure Messaging	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Bill Pay	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Forms / Questionnaires	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Notifications	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Telehealth	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Remote Monitoring	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Consent Management	[Yes/No]	[%]	[Yes/No/Partial]	[N]
Privacy Preferences	[Yes/No]	[%]	[Yes/No/Partial]	[N]

Health Literacy Assessment

Metric	Finding	Target	Status
Average reading level	[grade level]	6th-8th grade	[PASS/FAIL]
Medical jargon instances	[N]	0 in patient-facing text	[PASS/WARN]
Multilingual support	[N languages]	2+ for diverse populations	[PASS/FAIL]
Glossary / term definitions	[Yes/No]	Yes	[PASS/FAIL]

Accessibility Assessment

WCAG Criterion	Status	Issues
Color contrast (1.4.3)	[PASS/FAIL]	[details]
Keyboard navigation (2.1.1)	[PASS/FAIL]	[details]
Screen reader support (4.1.2)	[PASS/FAIL]	[details]
Touch targets (2.5.5)	[PASS/FAIL]	[details]
Alt text (1.1.1)	[PASS/FAIL]	[details]

PHI Exposure Risks

#	Feature	Channel	Risk	Severity	File	Fix

Detailed Findings

#	Area	Severity	File	Issue	Patient Impact	Fix

Engagement Gap Analysis

[Features that competing patient portals offer but this system lacks, ranked by patient value]

Recommendations

[Ordered by patient impact and implementation effort]

DO NOT:

• Modify any code -- this is an analysis-only skill.
• Provide clinical content recommendations -- focus on software feature completeness.
• Assume a specific patient population without evidence from the code.
• Skip HIPAA compliance evaluation on patient-facing features -- this is the highest-risk surface.
• Ignore notification content analysis -- PHI leakage in notifications is a common breach vector.
• Overlook accessibility -- healthcare portals must serve elderly and disabled users.
• Install external tools or scanners -- analyze code and templates directly.
• Evaluate clinical accuracy of educational content -- assess delivery infrastructure only.

NEXT STEPS:

• "Run /healthcare-compliance to audit regulatory compliance beyond patient-facing features."
• "Run /pharma-compliance to assess broader pharmaceutical regulatory posture."
• "Run /mobile-ux-patterns to evaluate the patient-facing mobile UX."

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /patient-engagement — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.