# HealthProbe - Claude/UI Agent Guide

## Read First

Before UI work, read:

1. [`../README.md`](../README.md)
2. [`../01-product/MVP-Specification.md`](../01-product/MVP-Specification.md)
3. [`../02-architecture/Implementation-Guide.md`](../02-architecture/Implementation-Guide.md)
4. this file

## Current UI Objective

HealthProbe is not an alert-first anomaly dashboard. It is a local Health DB Time Machine.

The UI should help the user:
- browse local observations over time;
- inspect how HealthKit-accessible data looked at a selected observation date;
- compare two local observations;
- understand appeared/disappeared/representation-changed records without assuming data loss;
- export selected point-in-time views and diffs;
- see archive/cache health and capture status.

## UI Ownership

Claude/UI owns:
- SwiftUI views in `HealthProbe/Views/`;
- view models in `HealthProbe/ViewModels/`;
- navigation and screen composition;
- visual design, accessibility, Dynamic Type, and legacy-device UI simplification;
- mock data for previews.

Claude/UI does not own:
- SQLite archive schema or analysis queries;
- Core Data cache model design or storage replacement strategy;
- HealthKit capture internals;
- recovery/salvage tooling;
- project entitlements or signing.

Cross-boundary needs should be expressed as protocols or view-ready DTOs.

## Target Screens

Current target surfaces:

```text
App
├── Dashboard / Capture Status
├── Observation Timeline
├── Observation Detail
├── Diff Detail
├── Data Types
├── Export Preview / Export History
├── Archive Status
└── Settings
```

Legacy/low-memory devices may get simplified tables and summaries instead of heavy charts. Capture, reporting, and export remain more important than visual richness.

## Legacy Device UI Mode

Use simplified UI when the app runs on iOS 15-era devices, very small screens, or when memory/performance instrumentation shows repeated pressure during chart/detail screens.

Simplify by:
- preferring tables and summary rows over dense charts;
- limiting default record previews;
- loading one detail surface at a time;
- using paged SQLite DTOs for drill-down;
- hiding non-essential visual comparisons behind explicit taps.

Do not remove:
- capture controls;
- archive health/status;
- cached report summaries;
- export flows;
- paged record inspection.

## Language Rules

Prefer:
- "records no longer visible in this observation"
- "representation changed"
- "consolidation likely"
- "aggregate changed"
- "cause not inferred"
- "export selected evidence"

Avoid:
- "Apple lost your data"
- "critical data loss" from counts alone
- "sync bug"
- "cross-device truth"
- "restore from HealthProbe"

## Design Guidelines

Tone:
- calm, technical, evidence-oriented;
- no emergency language unless the user explicitly chooses an interpretation;
- make uncertainty visible.

Visual hierarchy:
- summary first, details on demand;
- paged record tables for large datasets;
- chart only when it is cheap and helpful;
- no UI that implies all data is loaded in memory.

Controls:
- segmented controls for observation/diff modes;
- filters for type/date/source/change classification;
- export buttons only for explicit user-triggered actions;
- destructive actions require confirmation.

Accessibility:
- support Dynamic Type;
- keep tables readable on small devices;
- provide VoiceOver labels for charts and summary cards;
- avoid color-only meaning.

## Data Access Pattern

Views should consume:
- view models;
- protocols;
- paged DTOs;
- Core Data cached summaries once implemented.

Views should not:
- query the large SQLite archive directly;
- decode full record archives into arrays;
- mutate HealthKit;
- treat SwiftData as target architecture.

## Preview Data

Preview/mock data must be synthetic:
- no real health values;
- no real source names;
- no device identifiers;
- no real dates tied to a person.

Use examples such as:
- type: `step_count`
- value: `42`
- source hash: `source_hash_example`
- record hash: `record_hash_example`

## Completion Checklist

- [ ] UI copy follows Time Machine / observation language.
- [ ] No count-only critical loss messaging.
- [ ] Large record lists are paged or mocked as paged.
- [ ] Works on narrow/small-device layouts.
- [ ] Dark mode and Dynamic Type reviewed.
- [ ] VoiceOver labels exist for interactive elements.
- [ ] No real health values in previews/tests.
- [ ] No new dependency on SwiftData as target storage.
