existential-birds/beagle / plugins/beagle-ios/skills/healthkit-code-review
healthkit-code-review
VerifiedReviews HealthKit code for authorization patterns, query usage, background delivery, and data type handling. Use when reviewing code with import HealthKit, HKHealthStore, HKSampleQuery, HKObserverQuery, or HKQuantityType.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| references/authorization.md | markdown | 4.5 KB |
| references/background.md | markdown | 6.2 KB |
| references/data-types.md | markdown | 7.1 KB |
| references/queries.md | markdown | 6.2 KB |
references/authorization.md
View on GitHub# HealthKit Authorization
## Authorization Model
HealthKit uses **per-data-type, separate read/write authorization**. Users grant access individually for each health data type.
### Required Setup
1. **Entitlement**: `com.apple.developer.healthkit` capability
2. **Info.plist Keys**:
- `NSHealthShareUsageDescription` - Why app needs to **read** health data
- `NSHealthUpdateUsageDescription` - Why app needs to **write** health data
### HKAuthorizationStatus (Write Only)
| Status | Meaning |
|--------|---------|
| `.notDetermined` | User hasn't been asked yet |
| `.sharingAuthorized` | User granted write access |
| `.sharingDenied` | User explicitly denied write access |
**Critical**: Read permission status is intentionally hidden for privacy.
### Key Methods
| Method | Purpose |
|--------|---------|
| `isHealthDataAvailable()` | Check device support (not on iPad pre-iPadOS 17) |
| `authorizationStatus(for:)` | Check **write** permission only |
| `getRequestStatusForAuthorization(toShare:read:)` | Check if auth sheet would appear |
| `requestAuthorization(toShare:read:)` | Request permissions from user |
## Critical Anti-Patterns
### 1. Misinterpreting requestAuthorization Success
```swift
// BAD: success does NOT mean permission granted
healthStore.requestAuthorization(toShare: types, read: types) { success, error in
if success {
self.startRecordingWorkout() // May fail if permission denied!
}
}
// GOOD: success means dialog flow completed
healthStore.requestAuthorization(toShare: types, read: types) { success, error in
if success {
// Check specific type for write operations
if self.healthStore.authorizationStatus(for: workoutType) == .sharingAuthorized {
self.startRecordingWorkout()
}
}
}
```
### 2. Checking Read Permission Status
```swift
// BAD: Cannot determine read permission status
let status = healthStore.authorizationStatus(for: heartRateType)
if status == .sharingAuthorized { // This only checks WRITE status!
displayHeartRateData()
}
// GOOD: Just attempt to fetch - empty results if denied
func fetchHeartRateData() async {
let results = try? await healthStore.execute(query)
// Handle empty results gracefully
}
```
### 3. Not Checking Device Availability
```swift
// BAD: HealthKit not available on iPad (pre-iPadOS 17)
func requestHealthKitAccess() {
healthStore.requestAuthorization(toShare: types, read: types) { _, _ in }
}
// GOOD: Always check availability first
func requestHealthKitAccess() {
guard HKHealthStore.isHealthDataAvailable() else {
showHealthKitNotAvailableMessage()
return
}
healthStore.requestAuthorization(toShare: types, read: types) { _, _ in }
}
```
### 4. Widgets Requesting Authorization
```swift
// BAD: Widgets cannot present authorization UI
struct HealthWidget: Widget {
func getTimeline(...) {
healthStore.requestAuthorization(...) // Will silently fail
}
}
// GOOD: Use getRequestStatusForAuthorization in widgets
struct HealthWidget: Widget {
func getTimeline(...) {
let status = try? await healthStore.statusForAuthorizationRequest(toShare: [], read: types)
if status == .shouldRequest {
showOpenAppPrompt()
} else {
displayHealthData() // May be empty if denied
}
}
}
```
### 5. Accessing Data Before Authorization Completes
```swift
// BAD: Race condition (HKError code 5)
func initialize() {
healthStore.requestAuthorization(toShare: types, read: types) { _, _ in }
fetchHealthData() // Called before authorization completes!
}
// GOOD: Wait for authorization
func initialize() async {
do {
try await healthStore.requestAuthorization(toShare: types, read: types)
await fetchHealthData()
} catch {
handleAuthorizationError(error)
}
}
```
## HKError Codes
| Code | Constant | Meaning |
|------|----------|---------|
| - | `.errorAuthorizationDenied` | User denied permission |
| - | `.errorAuthorizationNotDetermined` | App hasn't requested yet |
| 4 | - | Missing HealthKit entitlement |
| 5 | - | Transaction failed (often premature data access) |
## Review Questions
1. Is `isHealthDataAvailable()` called before any HealthKit operations?
2. Is the `requestAuthorization` completion handler correctly interpreted?
3. Is there any attempt to determine read permission status? (anti-pattern)
4. Are all Info.plist usage description keys present with meaningful text?
5. Do widgets avoid calling `requestAuthorization`?
6. Is authorization status re-checked before write operations (not cached)?
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |