review Visibility internal Owner erik@uvilo.com Approver _ Created 2026-07-17 Updated 2026-07-17

Life Circumstances Vision

Vision

Uvilo’s life circumstances are the contextual layer that sits between a user’s identity and their life domain assessments. While life domains define what areas of life are measured (Body, Mind, Work, Money, etc.), circumstances define how those areas are experienced — the situational factors that shift relevance, weighting, and interpretation of quiz results. A user going through a divorce experiences the Intimacy, Community, and Money domains differently; a new parent experiences Time, Play, and Purpose differently. Circumstances capture this context so that recommendations are personalized, not generic.

The circumstance field schema already exists in draft form across two CSV files: Life_Circumstances_Table.csv (human-readable reference with ~90 fields across 8 categories) and Life_Circumstances_SQL.csv (SQL-compatible subset with ~30 structured fields). This project formalizes that work: promoting the schema from draft CSV to a validated, machine-readable format, defining the storage model (SQL for structured fields, vector embeddings for semantic fields), establishing how circumstances modify domain quiz scoring and conditional domain applicability, and creating a repeatable process for reviewing and updating circumstance data as Uvilo’s methodology evolves.

Background

Life circumstances originated as a standalone data definition outside the Forge project framework. The CSV files define fields across eight categories: Basic Personal Information, Living Situation, Professional & Financial, Education & Personal Development, Emotional & Psychological Patterns, Time Management & Productivity, Social & Relationship Dynamics, and Personal Goals & Lifestyle. Each field is designated as either SQL-stored (enums, strings, numbers, dates, booleans) or Vector-stored (embeddings for nuanced, free-text data like cultural background, fears, career goals).

Downstream consumers include the Life Domains project (which defines conditional domains — School, Work, Business, Parenting, Caregiving — whose applicability is determined by life circumstances) and the Domain Quiz project (which produces per-domain scores that circumstances contextualize). The Onboarding Quiz and Analytics projects also depend on a stable circumstance schema for personalization and segmentation.

Requirements

R1: Canonical circumstance schema

Publish the canonical set of life circumstance fields with complete, consistent metadata. Each field must have a stable identifier, category, label, storage type (SQL or Vector), data type, and validation constraints. All fields must be promoted from draft CSV to a validated, machine-readable format. The field set must be stable — existing field identifiers must not change without a versioned migration.

R2: Storage model — structured vs semantic

Define and enforce the storage model that distinguishes SQL-stored structured fields (enums, strings, numbers, dates, booleans with defined value ranges) from Vector-stored semantic fields (embeddings for nuanced, free-text data). The schema must make this distinction explicit so that downstream systems know how to store, query, and retrieve each field. SQL fields must have defined data types and value constraints; Vector fields must have guidance on what constitutes a valid embedding input.

R3: Circumstance categories

Organize fields into logical categories that reflect the structure of a user’s life context. The eight existing categories — Basic Personal Information, Living Situation, Professional & Financial, Education & Personal Development, Emotional & Psychological Patterns, Time Management & Productivity, Social & Relationship Dynamics, and Personal Goals & Lifestyle — must be preserved with clear definitions. Categories must be extensible for future additions without renumbering existing ones.

R4: Conditional domain applicability

Define how life circumstances determine which conditional life domains apply to a user. Five domains are conditional (School, Work, Business, Parenting, Caregiving), and their applicability must be derivable from specific circumstance fields (e.g., Employment Status determines Work applicability, Number of Children determines Parenting applicability). The mapping between circumstance fields and conditional domain triggers must be documented and machine-readable.

R5: Domain contextualization and weighting

Define how life circumstances modify domain quiz scoring, relevance, and interpretation. Circumstances must be able to adjust domain weighting (e.g., increase the relevance of Money during a divorce), flag domains that are acutely affected by a current situation, and provide qualitative context that the analysis bot uses when interpreting quiz results. The contextualization model must be documented so that the Domain Quiz analysis pipeline can consume it.

R6: Machine-readable output

Produce a validated JSON output file (Life_Circumstances.json) that downstream systems — Domain Quiz, Onboarding Quiz, Analytics, and the analysis bot — can consume directly. The output must be the single source of truth for circumstance field definitions, storage types, and conditional domain mappings, replacing the draft CSV files and ensuring all consumers work from the same data.

R7: Privacy and sensitivity handling

Classify circumstance fields by sensitivity level and define handling rules. Many fields are sensitive (sexual orientation, medical conditions, past traumas, financial situation, disabilities). The schema must include a sensitivity classification for each field and document privacy requirements for storage, retrieval, and use in personalization. Fields marked as sensitive must not be exposed in analytics or shared contexts without explicit user consent.

R8: Update process and skill

Maintain a skill for creating, reviewing, and updating circumstance data. The skill must cover: adding new fields, modifying existing field metadata, updating categories, promoting status from draft to published, validating changes against the schema, and updating the conditional domain mapping. The skill must ensure that changes are versioned and communicated to downstream consumers.

R9: Security review and safeguards

Because life circumstance data is sensitive and personally identifiable, downstream consumers must implement appropriate security safeguards. The schema and documentation must define security expectations at the schema and review level — not runtime implementation details. Specifically:

Access control expectations — The schema must annotate which fields are restricted-access (sensitive fields per R7) so downstream systems know to enforce role-based or consent-gated access.
Encryption and secret handling expectations — Documentation must state that sensitive circumstance fields require encryption at rest and in transit, and that no circumstance data may be logged in plaintext.
Auditability — Documentation must require that access to and modification of sensitive circumstance data is auditable (read/write logs), without prescribing the logging infrastructure.
Security review checkpoint — A security review must be completed before circumstance data is promoted to published status or consumed by downstream systems. The review must verify that sensitivity classifications, access-control annotations, and encryption expectations are present and consistent.

Success Criteria

#	Criterion	Measured by
V1	All circumstance fields have complete metadata and published status	JSON output has `status: "published"` for every field; no missing required fields
V2	Storage model clearly distinguishes SQL vs Vector fields with appropriate constraints	Each field has a `storage` property of `sql` or `vector`; SQL fields have data type and value constraints; Vector fields have embedding guidance
V3	All 8 categories are preserved with clear definitions and extensible structure	JSON output includes category definitions; no existing category renumbered
V4	Conditional domain applicability is derivable from circumstance fields with documented mappings	Each conditional domain (School, Work, Business, Parenting, Caregiving) has a documented trigger field and condition
V5	Domain contextualization model is documented and consumable by the analysis pipeline	Contextualization rules are defined in the output; analysis bot can read circumstance context when interpreting quiz results
V6	Output JSON is consumable by Domain Quiz, Onboarding Quiz, and Analytics	Downstream projects reference the canonical output path; no duplicated or stale circumstance definitions
V7	Every field has a sensitivity classification with documented handling rules	Each field has a `sensitivity` property; sensitive fields have documented privacy requirements
V8	A skill exists for creating, reviewing, and updating circumstance data	Skill documented with workflows for add, modify, validate, and publish operations
V9	Security safeguards are documented and a review checkpoint exists for sensitive circumstance data	Schema annotates restricted-access fields; documentation states encryption and auditability expectations; security review is required before publish or downstream consumption

Out Of Scope

Life domain definitions and metadata (Life_Domains project)
Quiz question authoring and scoring (Domain_Quiz project)
Onboarding quiz format and content (Onboarding_Quiz project)
Analytics implementation and dashboards (Analytics project)
User-facing UI for collecting or displaying circumstance data
Database or API infrastructure for serving circumstance data at runtime
Analysis bot implementation for interpreting quiz results with circumstance context

Charter Considerations

Stewardship — Life circumstances directly affect every Uvilo user. Changes to circumstance fields ripple through quiz contextualization, conditional domain applicability, and personalization. This project must ensure changes are versioned, validated, and communicated to downstream consumers. A corresponding requirement (R1: stable identifiers, versioned migration) has been added above.
Privacy — Many circumstance fields are deeply personal and sensitive (sexual orientation, medical conditions, past traumas, financial situation). Mishandling this data could harm users and violate privacy expectations. A corresponding requirement (R7: privacy and sensitivity handling) has been added above.
Security — Life circumstance data is sensitive and personally identifiable. Downstream systems that store, transmit, or process this data must apply appropriate security safeguards. A corresponding requirement (R9: security review and safeguards) has been added above, covering access-control annotations, encryption expectations, auditability, and a security review checkpoint before publish or downstream consumption.