Add maintainer onboarding documentation

2026-07-03 12:44:15 +02:00
parent 5d80af375e
commit d80486b25e
15 changed files with 1273 additions and 28 deletions
@@ -0,0 +1,92 @@
+# Roadmap And Risks
+
+## Near-Term Priorities
+
+1. Keep share intake reliable and conservative.
+2. Improve structured fact/date review UX.
+3. Stabilize private AI digest behavior with strong privacy tests.
+4. Verify iOS share/action extensions on physical devices.
+5. Decide which new local entities must sync to a backend.
+6. Reduce large UI files after behavior stabilizes.
+
+## Product Risks
+
+### Wrong profile matching
+
+Risk: a shared message gets attached to the wrong person.
+
+Mitigation:
+
+- prefer Share Inbox for ambiguous evidence
+- keep source links stable after user confirmation
+- test duplicate and near-match behavior
+
+### Over-eager AI check-ins
+
+Risk: old temporary status messages produce awkward current reminders.
+
+Mitigation:
+
+- preserve `sharedMessageDateTime`
+- include source age in digest context
+- instruct prompts to treat old health/status as historical evidence
+- prefer durable preferences when evidence is old
+
+### Privacy leakage
+
+Risk: raw names, sender details, or private text reaches scheduled digest
+prompts.
+
+Mitigation:
+
+- keep prompt builder tests strict
+- sanitize identity terms
+- exclude sensitive and unreviewed facts
+- keep AI results in review drafts first
+
+### Local storage migration mistakes
+
+Risk: changing aggregate JSON breaks existing installs.
+
+Mitigation:
+
+- default nullable fields
+- tolerant `fromJson`
+- focused migration tests
+- avoid destructive recovery paths
+
+### Native platform drift
+
+Risk: iOS/Android share, notifications, or background tasks compile but fail on
+real devices.
+
+Mitigation:
+
+- physical device test for native features
+- keep setup docs current
+- verify Podfile and Xcode project after plugin upgrades
+
+## Technical Debt
+
+- Aggregate storage is simple but will eventually limit multi-device sync and
+  conflict handling.
+- `PeopleView`, `DashboardView`, and Settings are large and should be split when
+  behavior changes require deeper edits.
+- Compatibility exports should remain stable but should not receive new logic.
+- Backend protocol does not yet cover every local-first entity.
+- Some full-suite widget tests are layout-sensitive.
+
+## Decision Backlog
+
+- Which entities are first-class backend resources?
+- Should AI suggestion drafts sync across devices or remain device-local?
+- Should source-message timestamp extraction support locale settings explicitly?
+- Should share inbox support batch triage?
+- Should preference signals be promotable to profile tags?
+- Should the graph explorer become its own feature slice?
+
+## Maintenance Rule
+
+When a roadmap item is completed or invalidated, update this file and the
+nearest feature doc. The old progress log is useful history, but this file
+should describe the current maintainer view.