[Feature Request] Opt-in self-assessment → Portland service navigation (rule-based first, AI second) — design doc for review

[coolshippdx]

Companion to #713 — third of three feature drafts from Shelter Now's lived-experience sessions. Same caveats as #713: draft for discussion, AI-assisted drafting from lived-experience requirements, opt-in only, and the consent/data-flow rules below are intended to be settled (with lived-experience testers and counsel) before any AI-assisted mode is built. Matching is rule-based first; we noticed tenantfirstaid is the org's active AI+housing project and would want to align any Stage 2 work with those maintainers.

---

PASS Design Doc — Feature 3: Opt-in Self-Assessment → Service Navigation

Status: DRAFT (local) — consent/data-flow doc precedes any build
Origin: Shelter Now LEC/VF sessions · Date: 2026-07-16

1. Problem

People don't know what exists: shelters, self-governed villages (Village
Federation network), transitional/permanent housing, recovery programs (Bybee
Lakes Hope Center, BHRC, Portland Rescue Mission), benefits navigation. An
opt-in self-assessment helps a person describe their situation and shows
matched services.

2. Non-negotiable data rules (defined BEFORE building)

1. Opt-in and deletable. Assessment answers are stored (if at all) in the
   user's own pod (PASS/Assessment/), never server-side; one-tap delete;
   an explicit "don't save my answers" mode runs the assessment in memory only.
2. LLM boundary: no pod documents, no names/DOB/contact info, and no
   Feature 2 data are ever sent to an LLM. Only the structured assessment
   answers (needs categories, household shape, coarse constraints) may be
   sent, and only in AI-assisted mode with its own consent screen naming the
   provider and retention. Default mode uses no AI at all.
3. Legal exposure: answers can include disclosures (immigration status,
   fleeing DV, substance use). The assessment must not ask for identifying
   detail, must show a "you can skip anything" banner, and needs counsel review
   of question list + consent copy before pilot. No data sharing with
   providers — output is information for the user, not a referral record.
4. Not a coordinated-entry/HMIS instrument. Explicitly not VI-SPDAT-like
   scoring; no vulnerability score is computed or stored.

3. Architecture: rules first, AI second

• Stage 1 (pilot): static question flow (~8–12 questions, branching,
  6th-grade copy, tap-first big-button answers) + rule-based matching
  over a curated directory. Deterministic, auditable, works offline once
  loaded. No consent complexity beyond "save answers?"
• Stage 2 (optional, later): AI assists in two bounded ways: (a) offline,
  maintainer-side — generating/adapting question wording and directory
  summaries (no user data involved); (b) online, opt-in — a guided-chat front
  end that fills the same structured answer object, so matching stays
  rule-based and inspectable.

4. Curated service directory data model

Static versioned JSON in-repo (src/constants/service_directory/portland.json)
so it works offline and deployments elsewhere can supply their own file:

{ id, name, kind: shelter|village|transitional|permanent|recovery|health|legal|benefits|day-services,
  audience: {adults, families, women, youth, veterans, couples, pets},
  constraints: {sobriety_required, id_required, referral_required, fee},
  access: how_to_get_in (plain language), phone, address, hours,
  geo: {lat,lng}?, languages[], last_verified (date), source }

last_verified is mandatory — stale info actively harms users; Shelter Now
owns quarterly verification for the Portland file. Seed list: Bybee Lakes Hope
Center, BHRC, Portland Rescue Mission, Village Federation villages, JOHS
shelters, Transition Projects, Blanchet House, Rose Haven, p:ear (youth), plus
211info as the fallback row.

5. Matching (Stage 1)

Pure function match(answers, directory) → ranked[{service, reasons[]}];
every result shows why ("open to couples; no sobriety requirement") and
what to do next. Zero-match always falls back to 211info + Shelter Now contact.
Unit tests enumerate answer-profile → expected-services fixtures reviewed by
Shelter Now program staff.

6. Consent & UX flow

Entry card: "Not sure what help is out there? Answer a few questions — private,
optional, nothing is shared." → questions (skippable, progress dots) →
results list → optional "Save this list / my answers to my pod." AI-chat mode
(Stage 2) gets a separate, explicit consent screen; declining leaves the
button flow fully functional.

7. Deliverables & order

(a) this consent + data-flow doc (lived-experience + counsel review);
(b) portland.json directory + verification runbook;
(c) Stage 1 prototype behind VITE_ENABLE_NAVIGATOR; (d) Stage 2 only after
(a)–(c) land and testers ask for it. Note: Code PDX's active tenantfirstaid
repo (housing/eviction legal chatbot) is the org's AI precedent — align the
Stage 2 approach with those maintainers rather than inventing a parallel stack.