# HealthProbe – Open Source Publication Guidelines

**Purpose:** Ensure documentation is accurate, responsible, and suitable for public release  
**Date:** 2026-05-01  
**Status:** Pre-publication review

---

## 1. Key Principles for Open Source

1. **Neutrality:** Describe *observed behavior*, not conspiracy
2. **Precision:** Distinguish between *facts*, *patterns*, and *theories*
3. **Humility:** Acknowledge unknowns and limitations
4. **Responsibility:** Don't speculate about Apple's intentions
5. **Reproducibility:** All claims must be testable

---

## 2. Content Review – Flagged Items

### 🔴 HIGH PRIORITY: Reframe Tone

**Issue 1: Section 2.1 "The September 2025 Mass Data Loss Event"**

**Current language:**
```
Suspected triggers:
  - Device migration (iCloud sync state transitions)
  - OS upgrade/downgrade cycles
  - Backup restore operations
  - HealthKit database re-indexing
  - iCloud sync divergence
```

**Problem:** Lists "suspected triggers" without evidence; reads like accusations.

**Revision for open source:**
```
**Preliminary observations from user reports suggest correlation with:**
  - Device migration or iCloud sync state changes
  - OS updates (particularly iOS 26.x)
  - Backup restore operations
  - Data re-indexing

**NOTE:** These are patterns observed in reports, not confirmed causal links.
Actual root causes require access to Apple system logs.
```

---

**Issue 2: "Root cause theories" sections**

**Current language:**
```
**Root cause theories:**
  - iCloud sync restoring from outdated backup
  - Third-party fitness app injecting historical reconstructions
  - HealthKit recovery logic applying retroactive corrections
  - Cross-device sync desynchronization
```

**Problem:** "Theories" is vague. Some are highly speculative; "third-party apps injecting" sounds accusatory.

**Revision for open source:**
```
**Possible mechanisms** (listed for documentation, not as conclusions):
  - iCloud sync merging data from outdated backup
  - Legitimate algorithmic recalculation (e.g., HR baseline updates)
  - Data misalignment across multiple devices during sync
  - Timestamp reconciliation during restore operations

**These possibilities are inferred from observed patterns, not system internals.**
Apple has not confirmed mechanisms.
```

---

### 🟡 MEDIUM PRIORITY: Add Disclaimers

**Issue 3: "Concrete observed cases" section 2.2**

**Current:** Lists examples without caveats.

**Add disclaimer:**
```
## 2.2 Observed Anomalies – Data Note

⚠️ **IMPORTANT:** These patterns have been observed in user reports and 
HealthProbe testing, but represent a limited dataset. They are NOT 
confirmed bugs, and may have benign explanations:

- Historical insertions could be legitimate corrections/backfills
- Silent deletions could be user actions or incomplete HealthKit queries
- Duplicates could be transient sync artifacts (self-healing within 24h)
- Divergence could reflect algorithm updates or device recalibration

HealthProbe documents *observations*, not diagnoses.
```

---

**Issue 4: "Why undetected" section**

**Current language:**
```
**Why undetected:**
- No notification from Apple Health
- Users discover loss retrospectively (weeks/months later)
- No audit trail to identify exactly *when* or *what* was lost
```

**Problem:** Reads like Apple is hiding data loss intentionally.

**Revision:**
```
**Why current mechanisms may not catch this:**
- Health.app provides no built-in audit trail for historical changes
- Data loss is often not immediately obvious (daily view may not change much)
- Users cannot easily compare snapshots over time
- Some anomalies resolve automatically within 24-72 hours (self-healing sync)
```

---

### 🟡 MEDIUM PRIORITY: Soften Certainty Language

**Issue 5: Executive summary opening**

**Current:**
```
Apple Health data loss events (confirmed Sept 2025 incident, ongoing sporadic reports)
```

**Problem:** "Confirmed incident" is too strong without official Apple acknowledgment.

**Revision:**
```
Reports of Apple Health data loss (September 2025 timeframe, ongoing user reports)
```

---

**Issue 6: Throughout documentation**

**Replace** these phrases:
| Current | Replace with |
|---------|--------------|
| "Apple Health data loss" | "Reported Apple Health data anomalies" or "User-observed data gaps" |
| "confirmed bug" | "potential issue" or "reported anomaly" |
| "undetected" | "not immediately visible to users" |
| "corrupted" | "inconsistent" or "unexpected state" |

---

### 🟡 MEDIUM PRIORITY: Privacy/Security Section Expansion

**Current Limitation:** Section 10 exists but is brief.

**Add to "Risks & Limitations" document:**

```markdown
## Important Caveats for Open Source Users

### What HealthProbe Cannot Know
- Whether data loss is a bug, user action, or legitimate system operation
- Exact root cause (only observations, not system internals)
- Cross-device behavior (requires manual export from multiple devices)
- iCloud backend state (only observes local HealthKit)

### What Users Should Understand
- **False positives expected:** Some "anomalies" may resolve automatically
- **Incomplete record:** Uninstalling HealthProbe loses all audit history
- **No guarantees:** HealthProbe itself could have bugs; don't rely solely on it
- **Comparison not validation:** Snapshot comparison detects differences, not errors

### Recommended Usage
- Use as **documentation tool**, not as truth source
- Export data regularly as backup
- Compare findings with iCloud.com Health export when possible
- Report patterns, not individual anomalies, to Apple
```

---

## 3. Content Audit Checklist

Before release, verify:

### Documentation Quality
- [ ] Every claim is either observable fact OR clearly labeled as theory/speculation
- [ ] "Suspected," "possible," "may" used where causality unclear
- [ ] Root causes described as inferences, not conclusions
- [ ] No language implying Apple intentionally hides issues
- [ ] Disclaimers present before speculative sections

### Technical Accuracy
- [ ] HealthKit API descriptions verified against Apple docs
- [ ] Code examples tested/executable
- [ ] Performance claims have measurement basis
- [ ] Known limitations documented explicitly

### Privacy Compliance
- [ ] No raw health sample data in examples
- [ ] HealthProbe CloudKit/iCloud sync is not described as a product goal
- [ ] User consent documented
- [ ] Data retention policy clear
- [ ] No tracking/analytics hidden in code

### Responsible Disclosure
- [ ] References to Apple issues are neutral, not accusatory
- [ ] Links to DearApple properly contextualized
- [ ] No suggestion of intentional misconduct by Apple
- [ ] Recommendations for bug reporting included

---

## 4. Specific Revisions Needed

### File: "Complete Specification & Motivations.md"

**Location:** Section 2.1 (3 major edits)
```
CHANGE: "Large-scale loss of Apple Health records reported"
TO: "Reports of large-scale Apple Health data anomalies"

CHANGE: Entire "Why undetected" subsection
TO: [See Issue #4 above]

CHANGE: All "suspected triggers" with confidence qualifier
TO: [See Issue #1 above]
```

**Location:** Section 2.2 (add disclaimer at top)
```
ADD: [See Issue #4 above - the full disclaimer block]
```

---

### File: "Forensics & Limitations.md"

**Location:** Section 1 "Known Limitations" (add)
```
ADD: Section 1.4 "Data Interpretation"

1.4 Data Interpretation Risks

HealthProbe documents observations, not diagnoses:

| Finding | What it means | What it does NOT mean |
|---------|---------------|----------------------|
| **Silent deletion detected** | Samples in snapshot A absent in B | Data is corrupted or lost forever |
| **Historical insertion** | Sample has old date, recent first-seen | Apple maliciously backdated data |
| **Duplicates found** | Multiple identical samples present | System is broken; may auto-deduplicate |
| **Divergence trend** | Metric value changing over time | Algorithm bug; could be calibration or update |

Always validate findings before drawing conclusions.
```

**Location:** Section 2.1 "Privacy Risks"
```
CHANGE: "CRITICAL: user's personal health history exposed"
TO: "CRITICAL RISK IF: raw health data were exfiltrated"
(Emphasis: HealthProbe doesn't do this)
```

---

### File: "Implementation Guide.md"

**Add Section:** 0.5 "Ethical Implementation Notes"

```markdown
## 0.5 Ethical Implementation Notes

As an open-source health monitoring tool, HealthProbe should:

1. **Never store/transmit raw health data**
   - Code review required before adding any health sample export
   
2. **Always ask before background operations**
   - Background fetch enabled only with user consent
   - Notify user of sync frequency in settings
   
3. **Respect user autonomy**
   - Easy to disable all monitoring
   - Easy to export/delete all data
   - Audit trail visible to user (not hidden)

4. **Accept limitations gracefully**
   - Don't claim certainty you don't have
   - Document where you're guessing
   - Encourage validation via Apple's tools
```

---

## 5. External References & Linking

### How to Reference DearApple Issues

**Current:** Direct references to issues as "bugs"

**Revision:** Neutral framing

```markdown
**BAD:**
"See DearApple Issue #001 – mass data loss bug"

**GOOD:**
"See DearApple Issue #001 – documented reports of Apple Health data loss"

**BETTER:**
"For additional context on the observed anomalies, see [DearApple Issue #001]
(https://github.com/overbog/dear-apple/issues/...) which collects user reports
of similar patterns."
```

---

## 6. README & Contributing Guidelines

**Add file:** `CONTRIBUTING.md` (for open source)

```markdown
# Contributing to HealthProbe

## Data Integrity First

When reporting anomalies or contributing code:

1. **Distinguish facts from theories**
   - Observed: "On 2026-03-15, step count dropped from 5000 to 2500"
   - Theory: "This might be due to iCloud sync"
   - Avoid: "iCloud sync corrupted my data"

2. **Include evidence**
   - Screenshots of HealthProbe audit trail
   - Export from Health.app for comparison
   - Device model, iOS version, app version

3. **Respect privacy**
   - Redact dates if identifying
   - Remove specific health values if sensitive
   - Mention: (e.g., "10 days of step data" not exact values)

4. **Acknowledge unknowns**
   - "I observed X, but I don't know if it's a bug or expected behavior"

## Code Standards

- Read-only HealthKit operations only
- No exfiltration of raw health data
- User consent required before new data collection
- Audit trail for all operations
```

---

## 7. Release Checklist

Before tagging v1.0.0:

- [ ] All flagged content revised (Issues #1-6)
- [ ] Added disclaimers in 3 places (Issues #3, #4, #7)
- [ ] Softened certainty language throughout (Issue #5)
- [ ] Privacy/Security section expanded (Issue #4)
- [ ] Added "Ethical Implementation" section to code guide
- [ ] New CONTRIBUTING.md with data integrity guidelines
- [ ] License file present (recommend: MIT or Apache 2.0)
- [ ] README includes clear link to DearApple context
- [ ] Code examples tested and run-verified
- [ ] No hardcoded debugging/logging left in
- [ ] Legal review of liability disclaimers

---

## 8. Statement of Purpose (For README)

```markdown
## Purpose

HealthProbe is a **documentation and monitoring tool** designed to help users 
understand their Apple HealthKit data state over time.

**It is NOT:**
- A diagnostic tool (cannot confirm bugs)
- A data recovery tool
- A security auditing tool
- A replacement for Apple's Health app

**It IS:**
- A local audit trail (what changed, when)
- An anomaly detector (unusual patterns documented)
- A forensic aid (exportable evidence for bug reports)
- Privacy-respecting (all local, no exfiltration)

**Appropriate uses:**
- Personal monitoring of your own health data
- Documenting anomalies to report to Apple
- Researching HealthKit behavior (with proper ethics)
- Contributing data to DearApple investigation (with consent)

**Inappropriate uses:**
- Claiming definitive proof of bugs without Apple confirmation
- Identifying or tracking other users
- Replacing professional medical advice
- Distributing unvalidated health data claims
```

---

## 9. Review Before Publish

Suggested external reviewers:
1. **Apple developer relations** — verify no confidential info disclosed
2. **Privacy researcher** — check data handling assumptions
3. **Legal counsel** — health data liability disclaimers
4. **DearApple maintainers** — coordinate messaging

---

## Summary: Key Changes for v1.0.0 Public Release

| Issue | Severity | Action | Effort |
|-------|----------|--------|--------|
| Tone: "confirmed bug" → "reported anomaly" | 🔴 HIGH | S&R in 3 docs | 30 min |
| Add data interpretation disclaimers | 🟡 MED | New section in Forensics | 45 min |
| Soften causality language | 🟡 MED | S&R throughout | 20 min |
| Add ethics section to Implementation | 🟡 MED | New section | 30 min |
| Create CONTRIBUTING.md | 🟡 MED | New file | 30 min |
| Final legal/privacy review | 🟡 MED | External | 2-4 hours |

**Total estimated effort:** 3-5 hours to make publication-ready

---

*HealthProbe – Open Source Governance v1.0*
