Situation Finder & Structured Guidance
Relevant source files
The following files were used as context for generating this wiki page:
- artifacts/mobile/content/guidance/items.ts
- artifacts/mobile/content/guidance/types.ts
- attached_assets/Pasted-Refactor-the-hospice-guidance-content-into-a-structured_1774841115565.txt
- attached_assets/Pasted-The-goal-of-the-application-is-to-give-caregivers-patie_1773692362618.txt
- artifacts/api-server/src/intelligence/hospice/planner.ts
- replit.md
The Situation Finder and Structured Guidance system serves as the primary actionable resource for caregivers and patients within the Hospice Roadmap platform. Unlike a general medical encyclopedia, this system is designed to provide immediate, step-by-step guidance for real-world scenarios encountered throughout the hospice journey. It categorizes complex clinical information into plain-language situations—such as breathing difficulties, equipment failure, or emotional distress—and delivers structured responses that prioritize safety and comfort.
Sources: attached_assets/Pasted-The-goal-of-the-application-is-to-give-caregivers-patie_1773692362618.txt, replit.md
System Architecture
The guidance system is built on a retrieval-based architecture. It identifies user intent from natural language or category selection, maps the request to a structured scenario, and retrieves approved content blocks. This ensures that the AI-driven Ragna AI companion remains grounded in clinically governed data rather than generating unverified medical advice.
Data Flow Overview
The following diagram illustrates how user input is processed to return structured guidance:
A summary of the logic used to match user needs to specific knowledge blocks.
Sources: attached_assets/Pasted-The-goal-of-the-application-is-to-give-caregivers-patie_1773692362618.txt, artifacts/api-server/src/intelligence/hospice/planner.ts
Content Model
Guidance is organized into GuidanceContentItem objects. Each item contains metadata for filtering and clinical governance, alongside the instructional content.
Data Structures
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (e.g., breathing-changes). |
categoryId | GuidanceCategoryId | Primary domain (e.g., symptoms, equipment). |
urgencyLevel | GuidanceUrgency | Severity: immediate, soon, routine, or planning. |
stages | GuidanceStage[] | Journey stages: before, during, or after. |
tags | string[] | Keywords for search and scenario mapping. |
governance | GuidanceGovernance | Includes owner, review date, and approval status. |
Sources: artifacts/mobile/content/guidance/types.ts:44-77, artifacts/mobile/content/guidance/items.ts:1094-1108
Structured Response Sections
To maintain consistency and safety, every guidance entry must include specific sections:
- What You May Notice: Plain-language clinical signs or observations.
- What It Means: Context and normalization of the situation.
- What To Do Now: Numbered, actionable steps for the caregiver.
- What To Avoid: Critical safety warnings and "hard stops."
- When To Call Hospice: Specific triggers for professional escalation.
Sources: artifacts/mobile/content/guidance/items.ts:40-67, attached_assets/Pasted-The-goal-of-the-application-is-to-give-caregivers-patie_1773692362618.txt
Knowledge Domains
The guidance catalog covers several major domains to support the full end-of-life journey:
Symptom & Comfort Management
Provides protocols for acute physical changes. Examples include:
- Breathing Changes: Managing labored breathing or "death rattle" using positioning and fans.
- Agitation/Restlessness: Identifying terminal restlessness and providing a calm environment.
- Pain Management: Guidance on using breakthrough medications and recognizing non-verbal cues.
Equipment & Caregiving
Technical and physical support for home-based care:
- Oxygen Concentrators: Troubleshooting alarms and power failures.
- Bed to Chair Transfers: Body mechanics for safe patient movement.
- Mouth Care: Maintaining oral hygiene for unresponsive patients.
Scenario Mapping and Urgency
The planner.ts module determines the appropriate response plan based on the urgency of the detected scenario.
The logic used to determine which response sections are required based on the situation's severity.
Sources: artifacts/api-server/src/intelligence/hospice/planner.ts:38-75, artifacts/mobile/content/guidance/items.ts:31-101
Search and Retrieval Logic
The Situation Finder uses a multi-layered search approach to connect users to the correct GuidanceContentItem:
- Direct Category Browsing: Users navigate via pre-defined categories like "Medications" or "End of Life."
- Full-Text Search: Scans
title,subtitle,summary, andtags. - Scenario Recognition: The AI Intelligence Engine uses a
scenarioMapto detect intent from "panic language" (e.g., "he's gasping" or "machine is beeping").
Sources: attached_assets/Pasted-Refactor-the-hospice-guidance-content-into-a-structured_1774841115565.txt, replit.md, artifacts/api-server/src/intelligence/hospice/planner.ts:16-25
Clinical Governance
All guidance content is subject to strict clinical governance. Every item in the guidanceItems array includes a governance block.
// Example Governance Structure
const DEFAULT_GOVERNANCE: GuidanceGovernance = {
owner: "Unassigned",
reviewDate: null,
approved: true,
version: "1.0.0",
sourceType: "clinical_editorial",
};
Sources: artifacts/mobile/content/guidance/items.ts:11-17, attached_assets/Pasted-The-goal-of-the-application-is-to-give-caregivers-patie_1773692362618.txt
Summary
The Situation Finder & Structured Guidance module is the clinical core of the Hospice Roadmap application. By combining a structured data model with a retrieval-based intelligence engine, the system delivers immediate, safe, and compassionate instructions to caregivers when they need them most. It bridges the gap between complex medical information and the high-stress reality of home hospice care.