Parasym V0 1

project Search related

Generated 2026-06-22 by the planning-and-task-breakdown skill from the [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) pack. Vertical slicing, S-M sized tasks, checkpoints every 2-3 tasks. Scope: Parasym rev 3 (signed off 2026-06-22, realtime workout mode deferred to v0.2).

Overview

Parasym v0.1 is a local-first, open-source iOS app that connects to a Morpheus M7 (or any BLE 4.0 chest strap exposing R-R intervals) and correlates the realtime HR + HRV data with Apple HealthKit to produce personalized health insights. v0.1 = 6-8 weeks of focused build. MIT license, public GitHub, completely free. v0.2 owns realtime workout mode (HRR + motion fusion); v0.3 owns the TARS integration.

Architecture Decisions

  1. Local-first, no backend. Data lives on iPhone. Encrypted at rest with iOS Data Protection Complete. CloudKit is v0.3+, optional. Rationale: OSS + free can't sustain a paid cloud bill; privacy is the differentiator.
  2. M7 as gold standard; compute both RMSSD + SDNN from the same R-R intervals. When M7 is connected, derive both metrics from one source (consistent math, no mismatch). When M7 is not, fall back to Apple Watch SDNN. Resolves Hrv Sdnn Vs Rmssd.
  3. Vertical slicing. One complete user-facing feature per task (BLE → live HR → HRV → HealthKit → trend → insight → export), NOT horizontal layers. Each task ships working, testable functionality.
  4. Foundation task sets architectural constraints. SwiftData schema includes privacy flags (sensitive types: weight, GPS). Settings uses SettingsSection / SettingsRow pattern. Insights produce NARRATIVE outputs (what + why + when + citation). Costs ~10% in Task 0; makes v0.3 TARS integration cheap.
  5. Public GitHub from day 1. Repo created before Task 0. README, LICENSE, contribution guide, CoC are Task 0 deliverables.
  6. No iCloud sync in v0.1. CloudKit is v0.3+.
  7. iOS 17+ minimum. SwiftData requires it.
  8. Swift 5.10+, NOT Swift 6 strict concurrency. v0.3 cleanup. Swift 6 strict mode + CoreBluetooth + HealthKit + SwiftData has known gotchas.

Dependency Graph

Foundation (Task 0)
├── Xcode project + folder structure
├── SwiftData stack + schema with privacy flags
├── Settings architecture (SettingsSection / SettingsRow)
├── GitHub repo (public, MIT)
└── README + contribution guide + CoC + CI stub

Data Layer (Tasks 1-4)
├── BLE (Task 1) → R-R interval stream
├── HRV compute (Task 2) → RMSSD + SDNN
├── HealthKit (Task 3) → SDNN, RHR, sleep, weight, workouts
└── Persistence (Task 4) → daily summaries, insights

Insight Layer (Tasks 5-7)
├── Insight engine (Task 5) → recovery score
├── Anomalies + notifications (Task 6) → 1σ/2σ alerts
└── Correlations (Task 7) → HRV vs sleep, RHR, training load

Surface (Tasks 8-10)
├── Export (Task 8) → CSV + JSON + Share Sheet
├── OSS polish (Task 9) → screenshots, icon, accessibility
└── CI (Task 10) → xcodebuild test + SwiftLint

Task List

Phase 1: Foundation

#### Task 0: Xcode project, SwiftData stack, public repo, OSS surface Description: Seed the project. Xcode project with iOS 17+ target, folder structure (Sources/, Tests/, Resources/), SwiftData stack with the schema that includes privacy flags (sensitive data types: weight, GPS). Settings architecture: SettingsSection / SettingsRow component pattern. Create public GitHub repo. Write MIT LICENSE, README, contribution guide, code of conduct. Stub GitHub Actions CI. Acceptance criteria:

Verification: xcodebuild build -scheme Parasym -destination 'platform=iOS Simulator,name=iPhone 15' succeeds. Repo visible on GitHub. Dependencies: None Files: Parasym.xcodeproj, ParasymApp.swift, ParasymSchema.swift, SettingsSection.swift, SettingsRow.swift, LICENSE, README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, .github/workflows/ci.yml (stub) Scope: S-M (1-2 days)

Checkpoint 1: After Task 0

Phase 2: Data Layer

#### Task 1: BLE — connect to M7 / Polar H10, decode R-R intervals, display live HR Description: CoreBluetooth: scan for BLE 4.0 heart rate monitors, connect to M7 (or any HRM exposing RR intervals over the standard Heart Rate Service UUID 0x180D). Decode the Heart Rate Measurement characteristic (UUID 0x2A37): parse flag byte, extract HR (8 or 16 bit), and R-R intervals (16-bit / 1024 second). Display live HR on a minimal dashboard view. Acceptance criteria:

Verification: xcodebuild test passes (mock BLE peripheral). Manual: pair M7, see live HR. Dependencies: Task 0 Files: BLECentral.swift, HeartRateParser.swift, RRIntervalStream.swift, HeartRateParserTests.swift, DashboardView.swift (minimal) Scope: M (3-5 days)

#### Task 2: HRV compute — RMSSD + SDNN from R-R intervals Description: On-device HRV computation from the M7's R-R interval stream. RMSSD (root mean square of successive differences) and SDNN (standard deviation of N-N intervals) using Apple's Accelerate framework (vDSP) for SIMD-accelerated math. Default 5-min rolling window. Display RMSSD + SDNN alongside live HR. Per Hrv Sdnn Vs Rmssd: when M7 is connected, derive both metrics from the same R-R intervals. Acceptance criteria:

Verification: xcodebuild test passes. Manual: connect M7, see RMSSD/SDNN update. Dependencies: Task 1 Files: RMSSDCalculator.swift, SDNNCalculator.swift, HRVWindow.swift, calculator tests, DashboardView.swift (extend) Scope: M (3-5 days)

#### Task 3: HealthKit — auth, query HRV SDNN / RHR / sleep / weight / workouts Description: HealthKit integration. Request authorization for: HRV SDNN, resting heart rate, sleep analysis, weight, workouts. Query latest samples via HKSampleQuery. Use HKAnchoredObjectQuery for incremental updates. Display Apple Watch HRV SDNN alongside M7 RMSSD with the metric-mismatch caveat surfaced in the UI. Acceptance criteria:

Verification: xcodebuild test passes (mock samples). Manual: grant access, see Apple Watch data. Dependencies: Task 0 Files: HealthKitAuthorizer.swift, HealthKitQuerier.swift, per-domain queriers, querier tests, DashboardView.swift (extend) Scope: M (3-5 days)

#### Task 4: SwiftData persistence + 7-day trend view Description: Persist daily HRV summaries, insight records, and HealthKit sync state to SwiftData. Build a trends view showing 7-day and 30-day HRV time series as a chart. Data model is JSON-exportable (Task 8 will use this). Acceptance criteria:

Verification: xcodebuild test passes. Manual: 7+ days of data, trends view shows the chart. Dependencies: Tasks 2, 3 Files: HRVDailySummary.swift, InsightRecord.swift, ParasymRepository.swift, TrendsView.swift, repository tests Scope: M (3-5 days)

Checkpoint 2: After Tasks 1-4

Phase 3: Insight Layer

#### Task 5: Insight engine — 30-day baseline, Galpin σ-deviation rule, daily recovery score Description: Implement the Galpin σ-deviation rule (per Hrv Sdnn Vs Rmssd; verified in gbrain chunks 6472/6475). Compute 30-day rolling baseline (mean + std dev) of morning RMSSD. Generate daily recovery score 0-100 (RMSSD-weighted). Gated on 30+ days baseline data — show "collecting baseline" UI before then. Insight engine produces NARRATIVE outputs (what + why + when + source citation) per Parasym Tars Integration design constraint. Acceptance criteria:

Verification: xcodebuild test passes. Manual: 30+ days of data, see daily score. Dependencies: Task 4 Files: InsightEngine.swift, BaselineCalculator.swift, DailyRecoveryScore.swift, SigmaDeviationRule.swift, engine tests, InsightsView.swift Scope: M (3-5 days)

#### Task 6: Anomaly detection + local notifications with quiet hours Description: Wire the σ-deviation rule from Task 5 to local notifications. When RMSSD deviates >1σ for 2+ days, send a yellow notification. When >2σ, send a red notification. User-configurable quiet hours. Notification text includes the insight narrative (what + why + when + citation) and a deep-link to the insights view. Acceptance criteria:

Verification: xcodebuild test passes. Manual: simulate 2σ drop, see notification. Dependencies: Task 5 Files: AnomalyDetector.swift, NotificationScheduler.swift, QuietHoursConfig.swift, detector + scheduler tests Scope: S-M (2-3 days)

#### Task 7: Correlation insights — HRV vs sleep, RHR, training load Description: Compute cross-source correlations: HRV vs sleep duration, HRV vs RHR trend, HRV vs training load (workout count or workout intensity per day). Surface as narrative insights with citations. Examples: "When deep sleep > 90min, RMSSD is 12% higher the next day." Acceptance criteria:

Verification: xcodebuild test passes (correlation math). Manual: 30+ days of data, see correlations. Dependencies: Task 5 Files: CorrelationEngine.swift, CorrelationInsight.swift, engine tests Scope: M (3-5 days)

Checkpoint 3: After Tasks 5-7

Phase 4: Surface

#### Task 8: CSV + JSON export with privacy flag stripping + iOS Share Sheet Description: Export all persisted data (daily summaries, insights, raw R-R intervals) to CSV and JSON. Privacy flag stripping: when a sensitive field (weight, GPS) is OFF in privacy settings, strip it from the export. Default: weight ON, GPS OFF. iOS Share Sheet integration. Acceptance criteria:

Verification: xcodebuild test passes. Manual: export 30 days, open CSV in Numbers. Dependencies: Task 4 Files: CSVExporter.swift, JSONExporter.swift, PrivacyAwareExport.swift, ShareSheetHelper.swift, exporter tests, ExportView.swift Scope: S-M (2-3 days)

#### Task 9: OSS polish — App icon, launch screen, accessibility, README screenshots, onboarding Description: App icon (custom, heart-rate or HRV motif), launch screen, accessibility (Reduce Motion, Dynamic Type, VoiceOver labels), README screenshots, onboarding flow that guides first-time users to pair M7 and grant HealthKit access. Acceptance criteria:

Verification: Manual: install on fresh iPhone, walk through onboarding. xcodebuild test passes (a11y tests). Dependencies: Tasks 1, 3 Files: AppIcon.appiconset/, LaunchImage.imageset/, OnboardingView.swift, onboarding step views, AccessibilityHelpers.swift, README.md (extend) Scope: S-M (2-3 days)

#### Task 10: CI — xcodebuild test on every commit + SwiftLint + coverage Description: GitHub Actions workflow that runs xcodebuild test on every push and PR. SwiftLint for code quality. Code coverage report. Status badge in README. Acceptance criteria:

Verification: Push a commit, CI runs and passes. Dependencies: Task 0 (CI stub) + Tasks 1-9 (tests) Files: .github/workflows/ci.yml (extend from stub), .swiftlint.yml, README.md (badge) Scope: S (1-2 days)

Checkpoint 4: After Tasks 8-10 (Final)

Risks and Mitigations

RiskImpactMitigation
M7 transmits RR intervals "too frequently" (Breath Ball docs) — needs decimationHighDecimate to 1Hz in HRVWindow (Task 2). Unit-test with high-frequency synthetic stream.
HealthKit SDNN is batched, not real-time — daily insight lacks "right now" feelHighUI surfaces timestamp: "Apple Watch HRV: 38ms (from this morning, 7:42am)". Manage expectations.
First 30 days = no daily recovery score (baseline gating)Medium"Collecting baseline" UI from day 1. σ-deviation rule still works on partial baseline.
Privacy defaults + settings architecture must be in place from Task 0MediumFoundation task sets architectural constraints. ~10% extra in Task 0 buys cheap v0.3 TARS integration.
M7 BLE connectivity quirks (off-brand devices, dropped connections)MediumBuild M7 + Polar H10 as the two tested devices. Add "Reconnect" affordance. Document unsupported devices.
Swift 6 strict concurrency deferred to v0.3LowExplicit decision. Swift 5.10+ is v0.1 target.
6-8 week timeline assumes focused workMediumPlan is modular. Each task is shippable independently. v0.1 is a v0.1.0 — can ship at any task boundary.
HealthKit auth on first launch is jarringLowOnboarding flow (Task 9) explains why we need it.

Open Questions (for the user)

  1. Bundle ID: com.nathanmaxwell.parasym? com.parasym.app? (Free choice, document in README. Affects App Store metadata.)
  2. App Store display name: "Parasym" or "Parasym HRV" or something else? (Affects App Store metadata, searchability.)
  3. TestFlight beta before App Store: ship to TestFlight first (private, 1 user = you)? Or skip and go straight to App Store review?
  4. First reading UX: guide to a "5-min morning baseline" reading on first launch, or just connect and let the user use it however they want?
  5. Onboarding copy: write the onboarding microcopy now, or stub it for v0.1 and iterate in v0.1.1?

Linked concepts

Source

Published and managed by TARS, an AI co-author built on Nathan's gbrain.