# Grief Galaxy: a family program with a game at its center

Design proposal · 7 September 2026 · US launch assumed · no operational backend changes made

## The recommendation

Build one six-week family program that can be delivered by a bereavement center, alongside teletherapy, or at home with optional parent coaching. Keep the educational content consistent; configure who helps the family, how materials arrive, and when activities happen. Make the basic unit **a family's week**, rather than a clinician visit or a game event.

Each week has a child activity, a small parent–child conversation, and an opportunity for the parent to ask for help. The kit makes that rhythm tangible. Coaching helps parents feel able to participate. The backend coordinates these experiences and makes unfinished work visible to the right person.

My starting recommendation is a partner-supported launch: a named site contact, a named clinical backstop, digital materials available immediately, and a single optional shipment containing individually numbered weekly envelopes. Avoid six separate shipments initially. Offer a parent coach as an additional delivery component whose benefit and workload you can test. Grant funding is a good setting for measuring the actual cost of supporting a family before committing to a commercial price.

Only three game sessions currently exist. Six weeks is the intended program structure, not a claim that six finished or validated sessions are available. Map the remaining content with the clinical team and freeze the complete study package before an efficacy trial.

## What the existing backend already supports

This assessment comes from the repository's source, not a production deployment audit. The source is substantially further along than a game analytics backend.

| Existing capability | Evidence in this repository | Direction |
|---|---|---|
| Treatment/content hierarchy and idempotent game events | `gg-data/schema.sql`, `gg-data/gg-data.js`, `collector.py` | Retain; version content and distinguish recreation from therapeutic activity |
| Partner sites, guide roles, care teams, sign-in and audit | `collector.py`, `schema.sql` | Retain; tighten assignment-level permissions and require explicit site membership |
| Enrollment, consent/assent fields, caregiver contact and family access | `schema.sql`, `collector.py` | Extend into versioned enrollment and household relationships |
| Weekly unlocks, messages and check-ins | `outreach.py` | Retain message infrastructure; replace one gate with separate task states |
| Parent discussion acknowledgement | `caregiver_talk`, `outreach.talk_submit()` | Extend from a weekly check-off into a planned activity with multiple possible outcomes |
| Kit address and a coarse shipment status | `signup.payload`, `signup.status` | Add fulfillment orders, inventory/version, delivery exceptions and replacements |
| Screening, referrals and follow-up waves | `screen.py`, `register.py` | Keep care screening; add a separate research schedule |
| Facilitated group sessions | `circle.py`, `circle.html` | Retain for centers; make participation and group membership explicit |
| Encryption, MFA and restricted-export mechanisms | `dbkey.py`, `collector.py`, `HIPAA.md` | Verify configuration and access tests; the presence of code is not proof of deployment compliance |

### Changes that matter before expanding delivery

1. **Help-seeking and access are coupled.** `checkin_submit()` raises a flag for a call request or a rough week; `flag()` defaults to holding the next key. A silent week also takes this path. Make routine support requests ordinary owned tasks. Clinical restriction should require a distinct, reviewable decision. Parents should not learn that asking for help prevents the child from continuing.
2. **Research timing depends on completion.** `screen.tick()` schedules mid/post from World 3/6 completion and follow-up from an answered post measure. That is useful for some care workflows, but it can systematically omit non-completers from an RCT. Research assessments need their own clock from randomization, including when games or earlier surveys are missed.
3. **Some permissions fail open for legacy accounts.** `site_scope()` returns no restriction for non-admin accounts without a site. Explicitly migrate those accounts, then deny unassigned staff access. Do not infer authorization from a missing site ID.
4. **The discussion record is too coarse.** `caregiver_talk` is unique per participant/week and updates its note/date on resubmission. It cannot cleanly distinguish a plan, an attempt, a reschedule, a completed conversation, or later correction. Preserve the history and the person reporting it.
5. **Existing safety heuristics need review.** Keyword matching in `screen_jar()` and thresholds adjusted solely by loss circumstance are operational rules, not validated clinical determinations. Review their evidence, who receives alerts, false alarms, and response capacity. Keep classifications, support needs, and clinician decisions distinct.
6. **Some documentation is stale.** The README describes real name/DOB fields and encryption support, but later says there are no names/DOB and only plaintext SQLite. Reconcile the docs against code and deployed configuration before partner onboarding.

## The family experience

### Before the first week

The partner introduces the program with a warm handoff. A coordinator checks eligibility, preferred language, accessible format, caregiver authority, safe contact details, technology access, and whether the family wants a kit. Program consent, child assent, research permission, messaging permission, and permission to share selected information are separate records.

The family chooses two realistic times: a **World Day** and a **Together Time**. Start with the discussion one to three days after play, adjustable to the family. A backup plan might be “after dinner on Thursday; if that does not work, during our Saturday walk.” This timing is a design hypothesis to test, not a prescribed clinical dose.

An orientation demonstrates one short conversation. The parent hears: “You don't have to explain grief perfectly. Your job is to listen, help your child feel understood, and let them stop.” The child hears what adults can see, what is optional, and how to ask for help. Never imply absolute confidentiality that the service cannot provide.

### A typical week

| Moment | Family experience | What the service records |
|---|---|---|
| Plan | Confirm or change World Day and Together Time | Planned times, time zone, preferences and later changes |
| Play | Child explores the world; parent nearby or alongside by agreement | Therapeutic activity progress separately from recreational surfing |
| Bridge | “This week, you can show your grown-up one thing you noticed.” Child can choose a general example | Only an explicitly shared selection, if any; not an automatic transcript |
| Prepare | Parent opens one envelope or the same digital card | Material/version available, not assumed read because delivered |
| Together Time | A 5–10-minute conversation, with a two-minute option | Not yet / tried briefly / did it / chose another time / would like help |
| Support | Optional parent check-in or scheduled coach contact | Need, owner, next action and outcome |
| Continue | Next activity becomes available under the family's plan | Separate availability, care review and research assessment states |

Default for ages 8–11: parent nearby, joins the introduction and brief closing; child handles the game. Default for ages 12–16: offer independent play, with the teenager choosing what to bring to the discussion. Age is a starting point, not an enforced rule. Support shared play when the child wants it or needs help reading. In teletherapy, the clinician can facilitate a portion directly. Do not require a parent to watch every answer.

### A concrete World 1 discussion card

**Front: “Make room for a reaction.”**

1. **Ask permission.** “Would you like to talk for a few minutes, draw, or do this another time?”
2. **Let the child choose.** “Was there a reaction in the game you want to talk about? It can be one a character had.”
3. **Reflect before advising.** “It sounds like ____. Have I understood?” Do not ask the parent to grade the child's grief or call a feeling bad.
4. **Offer a choice.** “Would listening, some company, or thinking of one small thing to try help today?”
5. **Close gently.** “Thank you for showing me. We can come back to this.”

**Back: a smaller version.** Name one reaction, say “That can make sense after a loss,” and spend two minutes together. Stopping or choosing a different time is allowed. The aim is a safe opportunity for conversation, not forced disclosure or a specific emotional outcome. This is proposed companion content for clinical review, not a substitute for the MGT manual.

The app's acknowledgement should ask about the opportunity and the parent's confidence, not request the child's story. Keep “Did your child seem comfortable?” optional and avoid treating it as a verified symptom measure. A quiet walk, drawing, or brief check-in can count as an attempted activity; do not automatically code every attempt as full delivery.

## Physical kit and digital equivalent

Ship one neutral outer package with a calendar, six numbered envelopes, an orientation card, and an age-flexible selection of small rewards. Each envelope contains that week's brief prompt, an optional longer prompt, a two-minute alternative, and a reusable closing ritual. Offer center pickup and printable copies. Postal delays never block digital content or urgent access to care.

The printed card and digital card share a content ID and version, such as `W1-TOGETHER-v1`. A QR code opens the corresponding general activity; access to personal records still requires appropriate authentication. Avoid bearer tokens, child names, loss details, or clinical scores in printed URLs or shipping labels.

For younger children, offer stickers and a constellation calendar. For older children, offer a choice: foil art cards, patches/bookmarks, a small creative journal, or matching ship customization and wallpapers. Test appeal rather than assuming that all teenagers dislike stickers. Rewards recognize participation and exploration; they never depend on disclosing painful material, reporting less grief, or giving the “right” personal answer.

Everything functional is available digitally: plan/reminder, conversation card, illustration activity, acknowledgement, and reward. “Digital only” remains a complete delivery option. Physical materials can be a valued cue and shared object without becoming an access requirement.

Suggested fulfillment states: requested → address confirmed → packed → dispatched → delivered or exception → replacement/closed. Store actual receipt separately from shipment. A coordinator can log center pickup. One household order can contain materials for multiple enrolled children, with each child's delivery recorded separately.

## Delivery models and ownership

| Setting | How it works | Who owns follow-through |
|---|---|---|
| Bereavement center, individual families | Site introduces program; family plays at home or on a center device; parent conversation follows | Named site guide/coordinator, with a clinical backstop |
| Bereavement center, group | Facilitator uses the existing circle controls; family conversation occurs separately, or is explicitly facilitated | Group facilitator; record group ID and attendance |
| Teletherapy adjunct | Therapist prescribes/reviews a world between appointments, or shares a portion in session; parent task is part of the agreed plan | Treating clinician; avoid a second contradictory coaching plan |
| Home with parent coach | Common orientation, asynchronous child play, parent task, scheduled brief calls | Assigned coach for participation support; named clinician for clinical decisions |
| Home with minimal routine contact | Digital program with clear support route and assessment/review plan | Named service owner; “self-directed” must not mean nobody owns incoming requests |

Do not pool these delivery models as though they were experimentally interchangeable. Existing teletherapy changes both clinical exposure and likely participant needs. The research plan proposes separate primary estimands for stand-alone and adjunct use.

### What a coach does

Start a 10–15-minute call with the parent: “How are you doing with all of this?” Ask what felt comfortable or difficult, rehearse one listening response, solve one barrier, and agree one next step. Record contact attempt, connected minutes, broad support topics, next plan, and any escalation. A coach is not a substitute for a treating clinician and does not need unrestricted access to the child's private narrative.

For a tested enhanced-coaching package, consider calls in weeks 1, 3 and 5 following a common orientation. That is a candidate intervention component, not a claim that three calls is the optimal dose. Routine callbacks requested by families and clinical rescue pathways remain available in every study condition.

Capacity should be computed from real work: completed calls + failed attempts + scheduling + documentation + supervision + clinical backstop time. For illustration only, 75 families × 3 calls × (15 conversation + 5 documentation minutes) is 75 hours per six-week cohort, or 12.5 hours/week. A 20% contact/scheduling allowance makes that 15 hours/week, before supervision, clinical assessment, or kit work. Replace every assumption with pilot logs.

## Backend design

### One enrollment, several independent clocks

Use `household → child enrollment → weekly plan → activities`. A visit remains a sitting, not the complete program. A child can play on Tuesday, talk on Friday, use another device, and see a therapist on Monday without creating four competing definitions of the week.

Maintain separate states for:

- **Program enrollment:** pending, active, paused, completed, withdrawn, transferred.
- **Game:** available, started, resumed, completed; recreation has its own kind and never satisfies a therapy requirement.
- **Conversation:** planned, available, attempted, completed, rescheduled, declined; keep reporter and history.
- **Support:** requested, assigned, attempted, connected, escalated, resolved; every open task has an owner and due time.
- **Clinical review:** requested, accepted by clinician, assessed, action planned, closed. Restriction of access is a separate decision with rationale and review date.
- **Kit:** order and fulfillment states, independent of play or clinical progress.
- **Research:** invited, consented, eligible, randomized, assessments due/completed/missed, follow-up continuing/withdrawn.

Stopping treatment, declining a card, and withdrawing research permission are different actions. Show the family simple choices while retaining the distinctions in staff records.

### Proposed entities

| Entity | Important fields and constraints |
|---|---|
| `household`, `household_member` | Roles, caregiver authority, communication recipient, effective dates; support multiple caregivers and siblings |
| `program_enrollment` | Child, site, delivery model, content version, planned start, owner, clinical backstop, status |
| `weekly_plan` | Enrollment, module ID, week ordinal, planned play/talk dates, time zone, availability rules; revision history |
| `activity_assignment`, `activity_attempt` | Type, version, required/optional, state, actual start/end, reporter, source, idempotency key |
| `discussion_report` | Assignment, attempted/completed/declined/rescheduled, duration band, optional caregiver support need; no required transcript |
| `kit_order`, `kit_item`, `shipment_event` | Household, child/module coverage, content/SKU version, protected address reference, dispatch/receipt/exception, cost |
| `support_task`, `contact_attempt` | Owner/team, reason, priority, due date, attempts, minutes, result, next action, escalation link |
| `clinical_review`, `care_restriction` | Clinician, evidence/source, decision, rationale, scope, review date; not a generic attendance flag |
| `consent_record`, `sharing_grant` | Subject/guardian, purpose, scope, form version, time, revocation; append changes |
| `study_enrollment`, `allocation` | Study version, household randomization ID, eligibility, immutable assigned components, timestamp, stratification values |
| `assessment_schedule`, `assessment_response` | Planned anchor/date/window, instrument/version, respondent, mode, masked assessment status, missingness reason |
| `delivery_exposure`, `protocol_deviation` | Assigned versus actually delivered component/dose, self-printing, kit refusal, added care, reason and author |

Keep contact/address data separate from gameplay and analysis tables, with restricted references. Do not label coded records anonymous: combinations of loss circumstances, dates, sites and demographics can still be identifying.

### Service boundaries

Use the existing application as a modular backend first, not a microservice rewrite. Separate authorization, enrollment/plans, fulfillment, support, content delivery, and research into explicit modules behind the existing routes. A transactional outbox dispatches messages and fulfillment requests with idempotency keys; external delivery failures never roll back clinical records. Store UTC instants plus the family's named time zone for scheduling.

Illustrative endpoints: `POST /enrollments/:id/plans`, `POST /assignments/:id/reports`, `POST /support-tasks`, `POST /kit-orders`, and a restricted `POST /studies/:id/allocations`. Commands validate permissions and current state server-side. Duplicate submission returns the existing result; edits append corrections. Study allocation occurs transactionally once per household and cannot be recreated by re-enrolling or refreshing a page.

Retain the current event log as evidence. Build read models for family progress and staff queues. Do not derive “conversation happened” from opening a QR code, “kit used” from delivered status, or “therapy complete” from a surfing reward. Server acknowledgements, not browser storage alone, determine clinical assignment completion across devices.

For an initial single-service pilot, a well-operated encrypted database may be sufficient; PostgreSQL becomes a reasonable migration candidate as concurrent sites, job processing, and research operations expand. Decide from deployment requirements and load tests, not a claim that changing database engines establishes compliance.

Migrate incrementally: retain existing participant/visit IDs and raw events; add enrollments, assignments and support tasks alongside them; import known consent and delivery facts with their source; mark missing historical dates or shipment outcomes unknown. Do not infer household authority from a shared surname or retrospectively label an opened page as a completed discussion. Compare old and new read models on a test copy, verify reconciliation and rollback, then switch staff worklists. Archive legacy behavior only after the corresponding task workflow is accepted.

### Permissions and visible information

| Role | Default view |
|---|---|
| Child | Own game and explicitly chosen sharing; understandable explanation of access and safety exceptions |
| Caregiver | Plans, materials, progress summary, their reports, support route; no automatic disclosure of every child answer |
| Coach/guide | Assigned households, participation, caregiver requests and relevant consented summaries |
| Clinician | Assigned care information, reviewed screening data, referrals and clinical decisions |
| Fulfillment | Recipient, delivery details and generic materials needed; no grief responses, scores, or notes |
| Research assessor | Contact needed for assessment and its schedule; assigned components masked where feasible |
| Analyst | Approved coded dataset with versioned fields; no routine access to contact data or narratives |
| Administrator | Account/operational functions; exceptional clinical access explicitly authorized and audited |

Confirm legal access rights and exceptions for the actual jurisdictions; the table is a product-access proposal, not a legal determination. HIPAA applicability depends on the entity and relationship; a teletherapy partnership can create business-associate obligations. COPPA is separately relevant to a child-directed service serving under-13s. Use these distinctions when reviewing vendors, retention, parental permissions and notices, rather than calling the whole system “HIPAA compliant” from its encryption setting. [HHS health app guidance](https://www.hhs.gov/hipaa/for-professionals/special-topics/health-apps/index.html), [FTC COPPA guidance](https://www.ftc.gov/business-guidance/resources/complying-coppa-frequently-asked-questions).

## Staff experience

Lead with work to do: families awaiting orientation; a parent asking for a call; a delayed kit; a discussion that was difficult; assessments coming due; a clinical review accepted but not closed. Every row shows owner, deadline and next action. Avoid a wall of red “noncompliance” markers.

A family timeline combines separate lanes: play, conversation, support, materials, clinical care and research. The staff member can distinguish “child played; parent hasn't had time” from “shipment missing,” “no functioning device,” and “family requested a pause.” The family home shows only this week's actions, a change-plan option, and a clear support route.

**Clinical responsibility must be operationally real.** Name the responding service, coverage hours, backup and urgent-care route before onboarding a site. Agree response targets with the service and display only commitments it can meet. A notification sent is not an assessment completed. An overdue clinical task escalates to another responsible person. Do not use game classification errors, skipped conversations or a keyword match alone as a diagnosis or automatic treatment-intensity decision.

## Priorities and acceptance criteria

### P0: a reliable partner pilot

1. Explicit site and case authorization. An unassigned guide cannot read another site's family, including direct URLs, exports and tokens.
2. Versioned enrollment and weekly plans. Rescheduling Together Time changes the plan and reminder without losing the original plan or falsely completing it.
3. Discussion states and owned support tasks. A routine call request creates a callback task while leaving access unchanged unless a clinician separately restricts it.
4. Basic fulfillment. A lost shipment opens an exception and the family immediately has the matching digital card; retry does not create a duplicate paid order.
5. Independent research scheduling. A participant who never completes World 1 still receives the pre-specified week-7 assessment unless contact permission is withdrawn.
6. Verified deployment controls and consent/sharing flows. Test the actual service configuration, restore process and vendor boundaries before live partner access.
7. A reviewed content manifest. Every assigned game/card is available, versioned and clinically signed off; unavailable Worlds 4–6 cannot be presented as ready.

### P1: reduce coordination work

Inventory/replacement reconciliation, appointment integration, multiple-caregiver access, assisted paper entry, content translations, masked assessment worklists and richer group delivery. Add EHR summaries only when the partner's workflow and permissions are clear.

### P2: after the delivery model has evidence

Automated shipping-provider integration, adaptive coaching rules, broader commercialization and new loss-specific packs. Hold off on automated clinical recommendation engines and a custom telehealth-video system.

## What success would mean

For a small usability/operations pilot, proposed go/no-go targets—not established benchmarks—are: at least 80% can start without staff troubleshooting; at least 70% attempt four of six Together Times; at least 85% provide the scheduled post assessment; every support request has a named owner; zero silent cross-site disclosures in access testing; and kit exceptions can be resolved without interrupting participation. Report confidence intervals and reasons, not just percentages.

Clinical success is improvement in elevated grief-related distress and functioning, with maintenance, measured independently of game use. Conversation quality, parenting confidence, participation, staff minutes and cost are explanatory and implementation outcomes; none substitutes for that clinical outcome. See [the trial design](RESEARCH-OPTIMIZATION-PLAN.md).

Track cost per enrolled family, engaged family, and additional clinically improved child. Include shipping, replacement, staff attempts, clinical oversight and research effort separately. For later commercial delivery, a partner license/per-family service charge plus transparent kit and support costs is easier to explain than charging for game minutes or promising symptom reduction. Pricing should follow observed costs and partner purchasing constraints.

## Next decisions

- **Clinical team:** content mapping, primary outcome instrument/permissions, eligibility, review/escalation protocol, limits of coaching and child-sharing policy.
- **Program lead:** initial delivery setting, staffing and backstop, kit versus digital preference policy, available languages and accessibility needs.
- **Research/statistics:** first optimization factors, target effect, sample/cost ceiling, family/group clustering, independent assessment operation.
- **Engineering/operations:** deployed-state audit, authorization migration, task schema, research clock and outbox validation.

Build the family weekly plan and the staff task queue first. These resolve the central coordination problem and support every delivery tier without rebuilding the game or the clinical content.