Core Product System (The Spine)

Core Product System (The Spine)

This document defines the canonical product architecture.

If implementation conflicts with these principles, implementation is wrong.

Key references:

1) Health State (single source of truth) #health-state

1.1 Definition

The Health State is the versioned “source of truth” for downstream systems. It merges four dimensions of reality:

  1. Subjective Reality: What the user feels (symptoms, mood, energy).
  2. Objective Reality: What sensors measure (HRV, glucose, sleep stages).
  3. Clinical Reality: What clinical data confirms (labs, imaging, clinician reports).
  4. Contextual Reality: Constraints and environment (diet patterns, meds, lifestyle).

1.2 The "Data Vampire" Strategy vs. Value-Based Reciprocity

We bias toward maximum data fidelity over time, but we overcome collection friction through Value-Based Reciprocity.

  • "Data Vampire": we ingest all available signals (frictionless passive sync + low-friction active logs).
  • Give-to-Get: every meaningful data request returns an immediate insight.
    • Example: User shares Sleep Data -> "Deep Sleep is low. This explains your 3 PM energy crash. Let's fix that."
  • Completeness Meter: gamifies the profile build by showing "Data Fidelity" levels and accelerators needed to unlock higher precision (e.g., "Add blood test to unlock Biological Age estimation").

1.3 Passive vs. Active Ingestion

  • Passive (Frictionless)
    • Wearables via HealthKit/Health Connect (Apple Watch, Oura, Whoop, Garmin).
    • CGM integrations (Dexcom, Libre) to see metabolic response to food.
  • Active (Low Friction)
    • Snap & Log Nutrition: Photo-first analysis of macros/micros (no manual entry).
    • Voice Journals: Natural speech parsed into structured symptom data.
    • Smart Scale: Daily weight and body composition sync.

1.4 Onboarding baseline + skepticism protocol

At onboarding we capture the user’s current frame:

  • Existing diagnoses (treated as Starting Hypotheses, not truth).
  • Medication reconciliation ("What are you taking?").
  • Goals, constraints, and the first minimal set of required fields (see Baseline Health State (BHS) in 06-Example-Program-Metabolic-Reset.md.
  • Skepticism Protocol: The system rigorously re-verifies historical claims against new Health State data, as patients are often misdiagnosed or conditions have changed.

1.5 Hydration process (how Health State becomes usable)

Health State “hydration” is deterministic and versioned:

  1. Ingest: Raw data flows in (JSON from APIs, Text from Chat, Images from Camera).
  2. Normalize: Units aligned (mg/dL vs mmol/L); timestamp alignment.
  3. Synthesize: The Health State Engine merges conflicting data (e.g., Oura vs Apple Watch sleep) using reliability scoring.
  4. Snapshot: Create a versioned HealthState_vN object.

This snapshot is what the Assessment Engine debates and the Protocol Engine optimizes.

2) Assessment Engine (explanations, not guesses) #popperian #multi-agent

The Assessment Engine is the system's "Brain." It is responsible for generating and testing explanations for the user's Health State.

Detailed Technical Specification: See 09-Popperian-Assessment-Engine.md for the multi-agent architecture and refutation protocol.

2.1 Epistemology: Explanatory Power vs. Probability

Most symptom checkers optimize for probability (inductive). We optimize for explanatory power:

| Feature | Standard "Symptom Checker" AI | Regain Health (Popperian Engine) | | :--- | :--- | :--- | | Logic | Inductive/Bayesian: "I've seen X with Y symptoms 1000 times, so it's probably Y." | Critical Rationalism: "I hypothesize Y. Does Y explain X? Is there any fact Z that makes Y impossible?" | | Goal | High Probability: Maximizing a statistical score. | Good Explanation: Finding a theory that is "hard to vary." | | Handling Evidence | Confirmation Bias: Looks for symptoms that match the disease. | Falsification: Actively looks for facts that refute the disease. | | Output | "You might have A, B, or C." | "Theory A is the best explanation because it accounts for X and Y, whereas B is refuted by Z." |

2.2 Hard-to-Vary Explanations (Deutsch)

David Deutsch argues that the hallmark of a good explanation is that it's hard to vary—its components are so interconnected that changing any detail would break the whole theory.

Why this matters: Easy-to-vary explanations can be adjusted to fit any data, which means they explain nothing. Hard-to-vary explanations make specific predictions; if they're wrong, they fail visibly.

Key criteria for hard-to-vary explanations:

  1. Every detail does explanatory work — no arbitrary components.
  2. Components are interdependent — change one, and others no longer fit.
  3. Specific and testable — makes predictions that can be refuted.

Deutsch's classic example (seasons):

  • Bad (easy to vary): "Winter happens because Persephone goes to the underworld, making her mother Demeter sad." (Why winter? Demeter is sad. Why sad? Persephone is gone. You can vary any detail—Demeter's mood, Persephone's location—without constraint.)
  • Good (hard to vary): "Winter happens because Earth's axis is tilted 23.5°, so the Northern Hemisphere receives less direct sunlight in December." (Change the tilt angle, and you change the severity of seasons. Change the month, and you change which hemisphere is cold. Every component is locked together.)

Medical application:

  • Bad: "You feel tired because of a virus." (Which virus? Why tiredness specifically? You can swap in "bacteria" or "stress" without any explanatory cost.)
  • Good: "Your fatigue is caused by Epstein-Barr reactivation. The virus infects B cells, triggering a cytokine response that causes the characteristic fatigue. Your elevated liver enzymes (ALT 67) confirm hepatic involvement, and the atypical lymphocytes on your CBC are the signature finding." (If you change "Epstein-Barr" to "common cold," the liver involvement and atypical lymphocytes no longer fit—the explanation breaks.)

In our Assessment Engine, we reject explanations that can be easily varied. We demand theories where each component is locked to the evidence—change one piece, and the whole thing collapses.

2.3 Mayo-style Multi-Agent Debate (Internal)

We simulate an integrated specialty team via Adversarial Multi-Agent Debate:

  1. Clinical Intake (The Interviewer): Compassionate listening (Mayo style). Unhurried data collection to build the "Problem Situation."
  2. The Conjecturer (Dr. House): Creative genius. Proposes bold candidate explanations without filtering yet (optimize for breadth).
  3. The Critic (Popperian Scientist): Rigorous skeptic. Tries to destroy the conjectures by finding ONE fact that makes a theory impossible (e.g., "Refute 'Common Cold' because fever is 40°C").
  4. The Synthesizer (The Mayo Lead): Wise senior physician. Selects the best surviving explanation that accounts for all facts without arbitrary tweaks.

2.4 The Popper Loop (Assessment Routine)

  1. P1: Problem Situation: Intake clarifies unexplained phenomena (e.g., OPQRST - Onset, Provocation, Quality, Radiation, Severity, Time).
  2. TT: Tentative Theories: Conjecturer generates candidates (e.g., Appendicitis, Gastroenteritis, Kidney Stone).
  3. EE: Error Elimination: The Critic attacks each theory with evidence.
    • Example: Attack on "Gas": "Refuted. Gas does not cause fever of 38.5°C."
  4. P2: New Problem: Synthesizer identifies the knowledge gap and the best next test/action (e.g., "Jump on your heels test to differentiate Appendicitis from Kidney Stone").

2.5 Handling Missing Information: The Fallback Protocol

If data is missing, refused, or unknown:

  • Acknowledge & Explain Epistemic Cost: "Without this info, I cannot rule out X, which increases uncertainty."
  • Counterfactual Branching: Run parallel simulations (Assume Positive vs. Assume Negative).
  • Safety-First Triage: If any hidden branch implies serious risk, default to the safest action (escalation).

2.6 Bidirectional HITL (Adversarial Check)

In high-stakes contexts, we create a Collaborative Intelligence Loop:

  1. AI Analysis: Agents debate and propose an Assessment.
  2. Clinician Review: Human clinician reviews the proposal.
  3. Respectful Challenge: If the clinician overrides the AI, the system critiques the override. "Clinician changed to X. Does X explain facts A and B better than our proposal? Is X refuted by evidence C (e.g., did the doctor ignore the high Calcium levels)?"
  4. Final Decision: Clinician acknowledges the discrepancy and proceeds.

Safety rules live in 05-Compliance-Safety-Privacy.md.

3) Protocol Engine (lifestyle-first optimization loop) #lifestyle-medicine

3.1 Philosophy: The KPI-Driven Optimization Contract

Most apps provide vague advice. We run a structured optimization loop with an explicit Optimization Contract.

  • The Goal: Bold, time-bound targets (e.g., "HbA1c < 6.5% within 180 days").
  • Debugging, not Blame: If outcomes stall, we don't say "try harder." We debug the biological bottleneck (e.g., "We missed the weight goal. Is high Cortisol preventing fat loss?").
  • Lifestyle-First Foundation: Nutrition, Sleep, and Exercise are dosed with the same precision as pharmaceuticals. Standard medical interventions are the safety net, not the foundation.

3.2 Specialized Protocol Agents

Just as the Assessment Engine uses specialists, the Protocol Engine uses a Rehabilitation Team:

  1. The Nutritionist (The "Bio-Chemist"): Optimizes biochemistry via plant-predominant, data-driven guardrails (focus on inflammation and micronutrient density).
  2. The Sleep Architect: Foundation of recovery. Optimizes light hygiene (lux timing), temperature control, and wind-down protocols.
  3. The Exercise Physiologist: Functional longevity. Prescribes precise "dosage" of Zone 2 Cardio, VO2 Max, and Resistance Training.
  4. The Mental Resilience Coach: Cortisol management via active recovery practices (meditation, breathwork).

3.3 ACLM 6 Pillars (The Protocol Spine)

| Pillar | Precision Approach | | :--- | :--- | | Nutrition | Data-driven guardrails; solve root biochemistry before patching symptoms. | | Physical Activity | Prescribed dosage (HR/duration) tracked and verified via wearables. | | Sleep | The Non-Negotiable foundation; bad sleep invalidates other gains. | | Stress Management | Active practices (HRV-tracked) instead of passive "relaxing." | | Risky Substances | Harm reduction as a foundational step for metabolic reversal. | | Social Connection | The "Blue Zone" factor; actively scheduled for biologicalmastery. |

3.4 Optimization Algorithm (Weekly Loop)

  1. Check-in: Adherence + barriers + subjective response.
  2. Update: Ingest new data and create a versioned snapshot (HealthState_vN).
  3. Explanation: What changed and what likely explains it (Assessment Engine).
  4. Adjustment: Fine-tune nutrition dose, sleep defaults, and movement Rx.
  5. Education: One micro-lesson explaining the "why" behind the change.

4) Education engine (gentle continuous learning) #ux

We teach reasoning, not rules, shifting the user from "Passive Patient" to "Active CEO of Health."

  • Micro-learning: Every request or change includes a short “why” (e.g., "Walking 20 minutes after a meal reduces your glucose spike by 30%").
  • Drip-Feed Curriculum: We employ a "Drip-Feed" model to gently shift mindsets across four stages:
    1. Awareness (Months 1-2): Connect habits to feelings (Logging + Correlations). Lesson: "Data sharing equals better care."
    2. Science of Reversal (Months 3-4): Introduce biological mechanisms (Insulin Resistance, Inflammation, Cortisol).
    3. Precision Mindset (Month 5): Introduce "Optimal Biological Alignment"—trust biomarkers over cravings.
    4. Mastery (Month 6+): Anticipation and autonomy; user becomes an expert on their own biology.
  • Channels: In-chat snippets, "Daily Wisdom" cards (< 30 sec), and visual correlation graphs.

5) UX model (Chat + Generative Artifacts + Visual mode)

5.1 Unified chat + generative artifacts

Chat is the command center, but not just text:

  • the system can render structured widgets (inputs, charts, check-ins)

Example interaction:

  • User: “I did a 30-minute run.”
  • System: renders a Workout widget (duration, intensity, RPE, save)

5.2 Triage-to-action flow

  1. conversational input
  2. internal reasoning
  3. best UI response (symptom flow, chart, booking, check-in)

5.3 Visual mode (secondary)

Used for dense review: history, dashboards, settings.

5.4 Editions / Mini-app constellation

Regain Health serves many focused experiences (“editions”) on one shared spine:

  • one identity + memory
  • one assessment engine
  • one protocol engine

Shared Context (The Magic): Because the backend is unified, editions talk to each other implicitly.

  • Scenario: Log a "High Stress" event in a Mental Health edition.
  • Effect: A Psoriasis edition sees this and warns: "High stress detected. Watch out for a flare-up tomorrow."

Editions are defined by configuration (theme, widgets, persona), not separate codebases.

Mini-App Factory: For the technical architecture of how these editions are generated on the fly, see 11-Generative-UI-Mini-Apps.md.

Back to Epistemology All Documents