HealthProbe – Claude Code Instructions

Project Context

HealthProbe is an iOS app that audits Apple HealthKit data integrity.
It detects anomalies: data loss, historical insertions, duplicates, divergence trends.
Full specification: HealthProbe/Doc/HealthProbe – Complete Specification & Motivations.md

Current state: Xcode scaffold only. ContentView.swift and Item.swift are default templates — replace them entirely.

Claude Code Scope: UI Layer

Claude Code is responsible for: - All SwiftUI Views (Views/ directory) - All ViewModels (ViewModels/ directory) - Navigation structure and tab/split layout - Design system (colors, typography, spacing) - Preview providers for all views - Accessibility (VoiceOver, Dynamic Type)

Claude Code does NOT own: - Services/ — HealthKit queries, anomaly detection, sync monitoring (see AGENTS.md) - Models/ — SwiftData models (see AGENTS.md) - Entitlements, Info.plist, project configuration

When services are not yet implemented, consume their protocols and use mock implementations for UI development.

Target Screen Structure

App (TabView)
├── Tab 1: Dashboard          → DashboardView
├── Tab 2: Anomalies          → AnomalyListView → AnomalyDetailView
├── Tab 3: Audit Trail        → AuditTrailView
├── Tab 4: Sync Status        → SyncStatusView
└── Tab 5: Settings           → SettingsView

DashboardView

Large status indicator: ✅ Healthy / ⚠️ Check / 🚨 Critical
Last check timestamp
Summary cards: samples tracked, anomalies found (all-time)
Up to 3 recent active alerts (tappable → AnomalyDetailView)
"Check Now" button (calls monitoring service)

AnomalyListView

List of DetectedAnomaly sorted by date (most recent first)
Filter: All / Critical / Warning / Info
Filter: by type (deletion, insertion, duplicate, divergence)
Each row: severity badge, type, sample type, date
Swipe to mark resolved

AnomalyDetailView

Full anomaly details
Evidence dictionary displayed as key-value rows
Severity badge
Share button → exports as Markdown (for bug reports)
"Mark Resolved" action

AuditTrailView

Chronological list of AuditTrailEntry
Each row: timestamp, event type chip, message
Search/filter by event type
Export button → JSON

SyncStatusView

Current iCloud sync state (chip: enabled / local-only)
Last sync timestamp
List of SyncStateChange events (most recent first)
Visual indicator when sync is stalled (no event in > 48h)

SettingsView

Check frequency: 2h / 6h / 12h / 24h (Picker)
Sample types to monitor (MultiSelect toggle list)
Alert thresholds (severity level for push notifications)
CloudKit sync toggle (off by default, with privacy disclaimer)
Export all data (JSON)
Delete all audit data (destructive, confirm alert)

Design Guidelines

Tone: Professional, calm, medical-adjacent. Not alarming unless critical.

Color System: swift // Status colors .healthyGreen // SF: green — all clear .warningAmber // SF: yellow — attention needed .criticalRed // SF: red — action required .neutralGray // SF: gray — informational / resolved

Typography: SF Pro (system font). No custom fonts.

Spacing: 8pt grid. Use VStack(spacing: 12) as baseline.

Icons: SF Symbols only. No third-party icon sets.

Key SF Symbols: - checkmark.shield.fill — healthy status - exclamationmark.triangle.fill — warning - xmark.shield.fill — critical - clock.arrow.circlepath — audit trail - antenna.radiowaves.left.and.right — sync - waveform.path.ecg — health data - doc.text.magnifyingglass — anomaly detail

Dark mode: Required. Test in both modes.

Privacy-first UI: - Health metric values are never shown in plain text in list rows - Values visible only in AnomalyDetailView after tap - Evidence dictionary values shown as monospace text, not highlighted

SwiftData Integration

Models are defined in Models/. Reference them read-only from views:

// In views, use @Query — never write directly from a View
@Query(sort: \DetectedAnomaly.detectedAt, order: .reverse)
private var anomalies: [DetectedAnomaly]

// Mutations go through ViewModels or services only

Until Models/ are implemented, use mock data via PreviewProvider.

ViewModel Pattern

// Pattern for all ViewModels
@MainActor
@Observable
final class DashboardViewModel {
    private let monitor: HealthMonitorProtocol  // protocol, not concrete type
    
    var status: HealthStatus = .unknown
    var recentAnomalies: [DetectedAnomaly] = []
    var lastChecked: Date?
    
    init(monitor: HealthMonitorProtocol = HealthMonitorService.shared) {
        self.monitor = monitor
    }
    
    func refresh() async {
        await monitor.runCheck()
    }
}

Always inject dependencies via protocols — makes previews and tests possible without real HealthKit.

Mock Data Protocol

Until services are ready, define preview mocks in Utilities/Mocks.swift:

struct MockHealthMonitor: HealthMonitorProtocol {
    func runCheck() async { }
    var status: HealthStatus { .warning }
}

extension DetectedAnomaly {
    static var preview: DetectedAnomaly {
        DetectedAnomaly(
            detectedAt: .now,
            type: "silent_deletion",
            severity: "warning",
            sampleType: "Steps",
            summary: "72 samples missing without deletion event",
            evidence: ["loss_count": "72", "loss_percent": "23.4"]
        )
    }
}

File Organization

HealthProbe/
├── Views/
│   ├── Dashboard/
│   │   ├── DashboardView.swift
│   │   └── StatusCardView.swift
│   ├── Anomalies/
│   │   ├── AnomalyListView.swift
│   │   └── AnomalyDetailView.swift
│   ├── AuditTrail/
│   │   └── AuditTrailView.swift
│   ├── Sync/
│   │   └── SyncStatusView.swift
│   └── Settings/
│       └── SettingsView.swift
├── ViewModels/
│   ├── DashboardViewModel.swift
│   ├── AnomalyListViewModel.swift
│   └── SyncViewModel.swift
├── Models/           ← NOT owned by Claude Code
├── Services/         ← NOT owned by Claude Code
└── Utilities/
    ├── Mocks.swift
    ├── DateFormatters.swift
    └── DesignSystem.swift

Privacy Directives

Mandatory — no exceptions: - No credentials, tokens, or API keys in any file - No personal data, device identifiers, or account identifiers - No real health values in code, comments, previews, or tests - Synthetic preview data only (see Mocks.swift above)

Before Marking a Task Complete

[ ] View renders in both Light and Dark mode (use Preview)
[ ] VoiceOver labels set on interactive elements
[ ] Dynamic Type tested (at least xSmall and AX3)
[ ] Works with mock data (no real HealthKit dependency in View layer)
[ ] No health values displayed without explicit user tap
[ ] Compiles without warnings