Assessment Mode

Part of the Anaya Care Handbook — the source of truth for how the product must behave. When the product needs to change, change this document first, then make the system match it.

Implementation status — audited against apps/backend/src/ai/agents/initial-assessment (the durable initialAssessment Restate workflow) and its apps/backend/src/ai/prompts/initial-assessment.prompts.md (system-interview + system sections) on 2026-07-24. The guided interview and structured generation now run as one durable workflow — the interview is shipped as the Initial Assessment Guided Narrative; the agency-configurable domain builder is not. ✅ In code · ⚠️ Partial · 🚧 Spec only (not yet built).

What this covers

This page governs Assessment Mode — user-facing name the Guided Narrative — the guided AI conversation that fills in an initial assessment. When a care manager launches it, the assistant walks them through the client's care setting and six Life's Milestones one topic at a time, asking conversational questions and forcing follow-ups whenever a gated topic is still uncovered. When every gated topic is covered it writes a warm narrative plus a Milestones Snapshot, and — in the same durable run — extracts the structured Simplified Routine Task Inventory, grounding every field in the interview transcript. It is optional and pre-client: an initial assessment can equally be filled in by hand, and there is no client record yet.

Assessment Mode is one way the assistant supports documentation; the broader AI documentation capability used during shifts (shift notes, incidents, symptoms) lives in AI Features. What the assessment itself contains is covered in Initial Assessments and Care Assessments; once the assessment is converted, the intake feeds AI care proposal generation.

Key terms

• Assessment Mode / Guided Narrative — the optional guided-intake conversation launched on an initial assessment; the code names it "Guided Narrative — Anaya Assessment Mode".
• Gated topic — one of the seven topics the interview must cover before it will generate: the care setting plus the six Life's Milestones. A gated topic cannot be skipped while it is still uncovered.
• Life's Milestones — the six GCS care domains: physical health & safety, nutritional needs, personal care assistance, cognitive & mental health, emotional support, and social engagement.
• Care setting — the seventh gated topic: where the client is coming from (for example post-hospital).
• Clarifying follow-up — a question the assistant asks (during the interview) to cover a still-uncovered gated topic, or (at generation time) a single source-cited clarification when a high-value fact is unclear.
• Narrative summary — the warm, person-first narrative the assistant writes, plus a Milestones Snapshot (one sentence per Life's Milestone) and a "Still to assess once care begins" block for milestones not covered at intake.
• Milestones summary confirmation — an optional care-manager-approved narrative framing that can be passed into generation.
• Logistics — practical details (weight/height, schedule, contact, pets, referral) the interview gathers but does not gate readiness on.

How it works

Launching the interview

A care manager launches the Guided Narrative from the initial assessment — it is an optional entry point ("Optional: Guided Narrative — a phone-call intake can auto-populate this assessment; not required for Ready status"), not a mode that turns on automatically. The assessment can also be completed by filling the form directly, without ever running it.

Walking the topics

The assistant covers the seven gated topics — the care setting plus the six Life's Milestones — asking conversational questions calibrated to each. It runs in short rounds of one to three questions and keeps going (up to about forty rounds, with at most two coverage-retry passes) until every gated topic is covered; a gated topic cannot be left uncovered. If an answer is vague or keyword-only, the assistant acknowledges it and asks for the missing detail rather than moving on. The user is never made to feel they did something wrong by giving a short answer. Logistics (weight/height, schedule, contact, pets, referral) are gathered along the way but do not gate readiness.

The topic set is fixed to the GCS Life's Milestones today, the same for every agency — there is no agency-configurable domain builder (see Initial Assessments AS-26).

Producing the narrative and pre-filling the inventory

Once every gated topic is covered, the durable run writes the narrative (plus the Milestones Snapshot and a "Still to assess once care begins" block) and, in the same run, extracts the structured Simplified Routine Task Inventory — every field grounded in the transcript, not re-derived from the prose. If a high-value fact is missing or ambiguous, the run pauses to ask the care manager one source-cited, choice-based question, then folds the answer in. There is no approve/reject review gate: the generated draft auto-saves as a Draft that the care manager owns and edits, and completing the initial assessment is the separate deliberate action (see Initial Assessments AS-2). The narrative is stored on the initial assessment and clones onward to the care proposal and client.

Rules

1. AMODE-1 — The Guided Narrative is an optional intake path a care manager launches on an initial assessment; it is not auto-activated and is not required to complete the assessment. (⚠️ Partial — built, but behavior changed from the original auto-activation spec)
2. AMODE-2 — The assistant guides the care manager through the seven gated topics — the care setting plus the six Life's Milestones — in a fixed three-phase flow (build the picture, add the human voice, check for gaps). (✅ In code)
3. AMODE-3 — For each topic the assistant asks simple, conversational questions calibrated to that topic's content. (✅ In code)
4. AMODE-4 — When an answer is vague or keyword-only, the assistant acknowledges the input and asks for the missing detail before it will treat a gated topic as covered. (✅ In code)
5. AMODE-5 — The interview runs in rounds of one to three questions, up to about forty rounds with at most two coverage-retry passes; a gated topic cannot be left uncovered. (There is no fixed "three follow-ups per topic" cap.) (✅ In code)
6. AMODE-6 — A user is never told they did something wrong for giving a short or single-word answer. (✅ In code)
7. AMODE-7 — The topic set is fixed to the GCS Life's Milestones today, the same for every agency; agency-configurable domains are a possible future direction only (see Initial Assessments AS-26). (🚧 Spec only — no agency configuration surface exists)
8. AMODE-8 — The gated topic set is the care setting plus the six Life's Milestones (physical health & safety, nutritional needs, personal care assistance, cognitive & mental health, emotional support, social engagement). Logistics are gathered but do not gate readiness. (✅ In code)
9. AMODE-9 — After every gated topic is covered, the assistant writes a warm narrative plus a Milestones Snapshot, and in the same durable run extracts the structured Simplified Routine Task Inventory, grounding every field in the transcript. (✅ In code)
10. AMODE-10 — Items that could not be covered at intake surface as a "Still to assess once care begins" block, and unclear high-value facts surface as source-cited clarification questions during generation. (✅ In code)
11. AMODE-11 — There is no mandatory review gate on the AI output: the care manager owns and edits the generated draft, and finalization is the initial-assessment completion check (AS-2), not an accept/reject step. An optional confirmed-Milestones summary may be passed in as approved framing. (✅ In code)
12. AMODE-12 — The finished narrative is stored on the initial assessment (there is no client yet) and carries over — a lossless clone — to the care proposal on convert, and onto the client record when a client is created. (✅ In code)
13. AMODE-13 — On convert, the narrative and the structured inventory clone into the care proposal; care-proposal care-plan generation grounds on the Simplified Routine Task Inventory functional assessment. (✅ In code)
14. AMODE-14 — Every generated narrative should end with a disclaimer footer stating it is documentation, not clinical interpretation. (🚧 Spec only — the intake narrative currently ends with the Milestones Snapshot and carries no disclaimer footer)

Who can do what

Decisions needed

• Whether to build agency-configurable intake domains (AMODE-7), or keep the GCS Life's Milestones as the canonical set.
• Whether to add the disclaimer footer (AMODE-14) — the intake narrative currently omits one — and, if so, its exact wording and whether agencies may customize it.
• How a "Still to assess once care begins" item connects to downstream work (a task, a reassessment, or a care-manager to-do) once the client exists.