Test-Data Hygiene Runbook¶

Epic: https://github.com/curaway-ai/curaway-backend/issues/1194 (D4) Added: 2026-05-25

The Core Rule¶

One persona per test account.

Multiple conversations per account are OK (new case_id, same patient_id). Multiple personae require multiple accounts. Persona pollution is a non-recoverable error — quarantine and replace.

A "persona" is a unique combination of: - Identity (name, age, gender, nationality) - Clinical presentation (diagnosis, condition, procedure type) - Intake scenario (caregiver vs. self, language, location)

Once a patient account carries clinical data for more than one persona, the analytics signal is degraded and the account cannot be rehabilitated without deleting historical conversations (which we never do — see Data Governance below).

What Pollution Looks Like¶

Signs an account has been re-used across personae:

Quarantine Procedure¶

When you discover a polluted account:

1. Do not delete it. Historical conversations must remain inspectable.

2. Run the quarantine script (dry-run first):

# Dry-run — prints what would change, no writes
railway run -s curaway --environment production -- \
    python scripts/quarantine_polluted_demo_patients.py

# Apply
railway run -s curaway --environment production -- \
    python scripts/quarantine_polluted_demo_patients.py --apply

For additional polluted accounts beyond the pre-configured list, pass their external_auth_id values:

railway run -s curaway --environment production -- \
    python scripts/quarantine_polluted_demo_patients.py \
        --apply \
        --extra-ids demo-patient-xyz-001 demo-patient-abc-002

1. Verify the flag was set:

SELECT id, external_auth_id, is_test_polluted
  FROM patients
 WHERE is_test_polluted = true;

1. Create a replacement account using scripts/seed_persona_accounts.py (or add a new function in app/seeds/seed_persona_accounts.py following the existing pattern).

2. Update this document — add the quarantined account to the table below.

Quarantined Accounts¶

Run scripts/quarantine_polluted_demo_patients.py --apply against production to actually set the DB flag for demo-patient-aisha-001. This PR only adds the column and script — the production write is a manual step for SD.

Clean Persona Accounts (#1194 D3)¶

Three clean replacement accounts are pre-seeded via scripts/seed_persona_accounts.py:

Each account ships with: - One Patient record (demographic only) - One empty Case (procedure identified, intake not started) - One ConsentRecord (clinical_data_processing granted) - No documents, no FHIR resources pre-loaded

Seeding the clean accounts¶

# Seed all three (idempotent):
railway run -s curaway --environment production -- \
    python scripts/seed_persona_accounts.py

# Seed a subset:
railway run -s curaway --environment production -- \
    python scripts/seed_persona_accounts.py --persona maria,meskerem

Abdul Moeed — Caregiver Gap¶

Abdul's scenario involves a mother-as-caregiver flow (Syeda speaks for her son Abdul Moeed). Caregiver relationship modelling is out of scope for this PR. The account is seeded as a plain patient record with an empty DOB. Follow-up tracked in https://github.com/curaway-ai/curaway-backend/issues/1194.

SQL: Filter Out Test and Quarantined Patients¶

Use both filters in analytics queries and Metabase dashboards:

-- Exclude test patients AND quarantined accounts
WHERE COALESCE(p.metadata->>'is_test', 'false') != 'true'
  AND p.is_test_polluted = false

Prevent Pollution Going Forward¶

Follow these rules when creating or using test patient accounts:

1. One persona per external_auth_id. Never reuse an account for a different name, nationality, or clinical presentation.

2. Use the E2E seed scripts — never create test patients manually in prod:

# All E2E personas (includes tkr, maria, abdul, meskerem):
railway run -s curaway -- python scripts/seed_e2e.py

# Clean persona accounts only:
railway run -s curaway -- python scripts/seed_persona_accounts.py

1. If you need a new persona, add a function in app/seeds/seed_persona_accounts.py following the existing pattern and register it in scripts/seed_e2e.py.

2. Never re-run an intake flow on an existing test patient to simulate a different clinical scenario — create a new patient account instead.

3. Heuristic alert: accounts with > 10 cases AND FHIR Conditions spanning 3+ ICD-10 chapter groups are flagged as "suspect polluted" by scripts/quarantine_polluted_demo_patients.py. Run the scan periodically:

railway run -s curaway -- python scripts/quarantine_polluted_demo_patients.py

Data Governance Constraint¶

Quarantined accounts are never deleted because:

• Historical conversations contain real AI agent decisions that must remain auditable (GDPR Article 5(1)(e) storage limitation applies to unnecessary data, but audit data is excluded under Article 17(3)(b)).
• The conversations may be needed to reproduce and debug reported clinical agent behaviour issues.

The is_test_polluted flag is the signal to downstream systems (analytics, matching, cohort analysis) to exclude the account. It does not restrict read access for authorised operators.

Downstream Readers (Wired — #1194 D5)¶

The flag is active: five code paths consult is_test_polluted and quarantined patients are filtered out of admin, cohort, and external-LLM surfaces. Seven additional sites intentionally do not filter on the flag — they cover auth, GDPR cascades, per-case workflows, and the quarantine script itself. The split keeps polluted accounts inspectable to authorised operators while preventing them from leaking into matching, analytics, or external MCP consumers.

Sites that filter (exclude polluted)¶

All filters use the NULL-safe form or_(Patient.is_test_polluted.is_(False), Patient.is_test_polluted.is_(None)) so rows that pre-date the column (NULL after ALTER TABLE) aren't accidentally hidden.

Sites that intentionally do NOT filter¶

To regenerate the audit, search for Patient.is_test_polluted, PatientRepository, and list_active callers and re-classify any new ones.

Related Files¶