Report Generation & Audience Management

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 — this module is specified but not yet built. Every rule below is 🚧 Spec only until the feature ships and this page is audited against the code. Legend: ✅ In code · ⚠️ Partial · 🚧 Spec only (not yet built).

What this covers

This page governs report generation: the engine that turns the data already captured across the platform into a finished, audience-specific report. The same underlying records — vital-sign readings, medication reminders, symptom logs, incidents, care-plan adherence, care-provider observations — are reshaped into different reports depending on who will read them. A doctor, a court-appointed conservator, a family representative, and a care manager each receive a report built from the same source data but filtered, worded, and authorized differently.

The engine has four responsibilities: aggregate the data for the reporting period, decide which content blocks belong in this audience's report, render each block in the right tone and format, and deliver the finished report only after the authorization that audience requires has been recorded. Two companion documents hold the developer-facing detail: the Report Audience Taxonomy (relationship, authority, tone, content, legal considerations, and delivery frequency for each audience) and the Report Generation Engine Spec (aggregation, block evaluation, rendering, delivery, and authorization).

Key terms

• Report engine — the system that produces a finished report through four steps: data aggregation, block evaluation, content rendering, and delivery with required authorization.
• Audience — the specific recipient type a report is built for. There are 13 audiences across 5 categories (see below); each one has its own tone, content rules, and authorization requirements.
• Template — the report shape chosen for one or more audiences. There are six: Health Snapshot, Formal Care & Welfare Report, Family Summary, Care Manager Dashboard, Transition of Care Summary, and Comparative Period Report.
• Content block — one section of a report (for example, vital-sign trends or incident summary). Each block is active, conditional, or excluded for a given audience based on the template configuration.
• AI-generated block — a content block whose wording Anaya AI drafts from the aggregated data. There are three, and every one needs human approval before the report can be delivered.
• Prior-period comparison — the same metrics computed for the period immediately before the report period, of equal length, so the report can tell new observations apart from ongoing patterns.
• Trajectory indicator — the engine's one-word read on the period overall: improving, stable, mixed, or declining.
• Authorization — the recorded sign-off a report needs before it can be delivered. Depending on the audience this is dual (two authorizers), single (one), optional, or not required.
• Health Snapshot — the health-data handoff template for medical recipients. (The PRD calls this the "Clinical Snapshot"; it is renamed here for the handbook's non-clinical voice.)
• Provider-contact boundary — the rule that the agency never reaches out to an outside party (doctor, APS office, legal representative) on its own; report generation never triggers external contact automatically.

How it works

When someone requests a report, they pick an audience. The audience determines the template, the template determines which content blocks are active, and the audience also determines what authorization the finished report needs before it can leave the platform.

The four steps

1. Data aggregation — the engine collects and computes every relevant metric for the reporting period from platform records (see Health Monitoring and Incident Reports), and computes the same metrics for the prior period of equal length.
2. Block evaluation — for the chosen audience, the engine decides which content blocks are active, which are conditional, and which are excluded.
3. Content rendering — each active block is written in the tone and format that audience requires. A doctor's Health Snapshot reads differently from a family member's Family Summary, even when both draw on the same readings.
4. Delivery — the finished report is routed to the recipient through the appropriate channel, but only after the required authorization has been recorded.

The 13 audiences, by category

• Clinical & Medical — Primary Care Physician (PCP); Medical Specialist; Home Health Nurse/Therapist.
• Legal & Protective Authority — APS Deputy/Social Worker; DPOA/Legal Decision-Maker; Conservator/Public Guardian.
• Family & Personal Network — Responsible Party; Secondary Family Member (view-only).
• Internal Care Operations — Care Manager; Company Administrator.
• Transition & Coordination — Hospital/Discharge Team; Hospice/Palliative Care Team.

The six templates

Content blocks

Reports are assembled from a fixed library of content blocks. For each audience, a block is active, conditional, or excluded. The library covers: vital-sign trends, medication adherence, symptom log, behavioral and cognitive observations, incident summary, care-plan adherence, care-provider observations, family interactions, welfare status, wellbeing summary, professional statement, and recommendations.

The behavioral and cognitive observations block is quantified, not anecdotal: it reports frequency, days observed, time-of-day patterns, and comparison against the client's baseline — never a free-text story.

Prior-period comparison and trajectory

Every report computes the prior period of equal length alongside the report period, so the reader can tell a new observation apart from an ongoing pattern. From the direction of the significant changes, the engine computes a single overall trajectory indicator — improving, stable, mixed, or declining. One critical metric that is declining forces the overall trajectory to "declining", no matter how much else improved.

Before a Comparative Period Report is generated, the engine validates both periods: each must have enough care data, the two must not overlap, and neither may include future dates. If a vital-sign threshold was reconfigured between the two periods, the report annotates the change so a shift in alert counts is not misread as purely health-driven.

The three AI-generated blocks

Three blocks are drafted by Anaya AI from the aggregated period data, and none can be delivered without human approval:

• Welfare Status Banner — Formal Care & Welfare Report only. A short, plain-language welfare position drawn from the period data, prior-period comparison, incident log, and supervisor notification trail. A care manager must review and approve it before the report is finalized. It must not include diagnostic labels, health assessments, or speculative language.
• Wellbeing Summary — Family Summary only. A warm summary that leads with what went well; concerns are framed with context and the agency's response. Care manager review is recommended before delivery.
• Professional Statement — Formal Care & Welfare Report only. A formal position covering welfare status, a no-evidence-of-neglect statement, and recommendations. Both a care manager and the supervising Company Administrator must authorize it before delivery. It must stay within the agency's scope of practice — no health diagnosis and no legal conclusions.

Authorization and delivery

Each audience defines the authorization a finished report needs before it can be delivered.

• Dual authorization (care manager and Company Administrator) — APS, DPOA, Conservator.
• Single authorization (care manager) — PCP, Specialist, Home Health, Hospital, Hospice.
• Optional / auto-delivery permitted — Responsible Party, Secondary Family, Care Manager (a care manager may review first, but it is not required).
• Auto-delivery, no authorization required — Company Administrator.

Every authorization is logged with the authorizer's identity and timestamp, immutably. A report cannot be delivered until its required authorizations are recorded. If authorization is not completed within 48 hours, the system escalates to the Company Administrator and sends reminders at 24 and 48 hours. Throughout, the provider-contact boundary holds: the engine never initiates contact with an outside party on its own.

Rules

1. RPT-1 — The report engine must carry out four steps for every report: aggregate the period data, evaluate which content blocks apply, render each active block in the right tone, and deliver only with the required authorization. (🚧 Spec only)
2. RPT-2 — The platform must support 13 audiences across 5 categories: Clinical & Medical (PCP, Medical Specialist, Home Health Nurse/Therapist); Legal & Protective Authority (APS Deputy/SW, DPOA/Legal Decision-Maker, Conservator/Public Guardian); Family & Personal Network (Responsible Party, Secondary Family view-only); Internal Care Operations (Care Manager, Company Administrator); Transition & Coordination (Hospital/Discharge Team, Hospice/Palliative Care Team). (🚧 Spec only)
3. RPT-3 — The platform must support six templates — Health Snapshot, Formal Care & Welfare Report, Family Summary, Care Manager Dashboard, Transition of Care Summary, and Comparative Period Report — each mapped to the audiences it serves. (🚧 Spec only)
4. RPT-4 — Each content block must be active, conditional, or excluded for a given audience based on the template configuration; no block may appear for an audience whose template excludes it. (🚧 Spec only)
5. RPT-5 — The behavioral and cognitive observations block must be quantified — frequency, days observed, time-of-day patterns, and baseline comparison — and must never be presented as narrative anecdote. (🚧 Spec only)
6. RPT-6 — Vital-sign thresholds used in a report must be read from each client's configured thresholds, never hardcoded. (🚧 Spec only)
7. RPT-7 — Every report must compute the prior period of equal length alongside the report period, so new observations can be told apart from ongoing patterns. (🚧 Spec only)
8. RPT-8 — The engine must compute one overall trajectory indicator — improving, stable, mixed, or declining — from the direction of the significant changes across the period. (🚧 Spec only)
9. RPT-9 — A single critical metric that is declining must force the overall trajectory to "declining", regardless of any other improvements. (🚧 Spec only)
10. RPT-10 — Before a Comparative Period Report is generated, the engine must validate that both periods have sufficient care data, do not overlap, and do not include future dates; a period that fails validation blocks generation and notifies the care manager. (🚧 Spec only)
11. RPT-11 — If a threshold was reconfigured between two comparative periods, the report must annotate the change so the deltas are not misread as purely health-driven. (🚧 Spec only)
12. RPT-12 — The three AI-generated blocks — Welfare Status Banner, Wellbeing Summary, and Professional Statement — must each be reviewed and approved by a human before the report can be delivered. (🚧 Spec only)
13. RPT-13 — The Welfare Status Banner appears on the Formal Care & Welfare Report only, requires care manager approval before the report is finalized, and must contain no diagnostic labels, health assessments, or speculative language. (🚧 Spec only)
14. RPT-14 — The Wellbeing Summary appears on the Family Summary only, must lead with what went well, and must frame any concern with context and the agency's response; care manager review is recommended before delivery. (🚧 Spec only)
15. RPT-15 — The Professional Statement appears on the Formal Care & Welfare Report only, requires both a care manager and the supervising Company Administrator to authorize it, and must stay within the agency's scope of practice — no health diagnosis and no legal conclusions. (🚧 Spec only)
16. RPT-16 — Reports for APS, DPOA, and Conservator audiences must require dual authorization by a care manager and the Company Administrator before delivery. (🚧 Spec only)
17. RPT-17 — Reports for PCP, Specialist, Home Health, Hospital, and Hospice audiences must require single authorization by a care manager before delivery. (🚧 Spec only)
18. RPT-18 — Reports for Responsible Party, Secondary Family, and Care Manager audiences may be auto-delivered with optional care manager review; reports for the Company Administrator are auto-delivered with no authorization required. (🚧 Spec only)
19. RPT-19 — Every authorization must be logged immutably with the authorizer's identity and timestamp. (🚧 Spec only)
20. RPT-20 — A report must not be delivered until all of its required authorizations are recorded; an external recipient who lacks the required authorization has delivery blocked, and the care manager is prompted to obtain it. (🚧 Spec only)
21. RPT-21 — If a required authorization is not completed within 48 hours, the system must escalate to the Company Administrator and send reminders at 24 and 48 hours. (🚧 Spec only)
22. RPT-22 — The report engine must never initiate contact with any outside party (healthcare provider, APS office, legal representative, or other external recipient) automatically; external contact requires explicit authorization from the responsible party or DPOA per the provider-contact boundary (see Care Coordination & Provider Integration). (🚧 Spec only)

Who can do what

Decisions needed

• Who can request a report, and can a representative request their own Family Summary on demand? The PRD names care managers and administrators as the operators of the engine but does not say whether a representative can self-serve a Family Summary. Options: representatives can pull a Family Summary on demand; reports are always generated by agency staff and delivered to the representative.
• What counts as "sufficient care data" for a comparative period? RPT-10 blocks generation on insufficient data but the threshold is undefined. Options: a minimum number of recorded readings or documented days per period; a per-block minimum; a configurable agency setting.
• What makes a metric "critical" for the declining-trajectory override? RPT-9 forces "declining" on a single declining critical metric, but the set of critical metrics is not enumerated here. Options: a fixed platform list; the client's vital-sign metrics that have thresholds configured; a care-manager-curated list per client.
• How should the engine word concerns in the Wellbeing Summary? RPT-14 requires leading with positives and framing concerns with context, but the exact balance is a content-policy decision. Options: a fixed positives-first structure with a single contextualized concerns section; care-manager-editable framing before delivery.
• Should optional-authorization audiences still leave an approval record when a care manager does review? RPT-18 makes review optional for Family, Secondary Family, and Care Manager audiences. Options: log the optional review as an authorization event when it happens; treat optional review as informal with no record.
• What is the delivery channel per audience? The engine "routes through the appropriate channel" but channels are not specified here. Options: in-platform delivery for internal and family audiences with a generated document for external recipients; configurable per audience in the Report Audience Taxonomy.