docs(04): capture phase context

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 00:39:35 +09:00
parent d0427219a2
commit 7fe6168106
1 changed files with 70 additions and 0 deletions
@@ -0,0 +1,70 @@
 # Phase 4: GPS & Power Optimization - Context
 **Gathered:** 2026-02-12
 **Status:** Ready for planning
 <domain>
 ## Phase Boundary
 Implement speed-adaptive GPS precision and lifecycle-aware power management. The app should use resources proportionally to what the user is doing -- high precision at speed, relaxed when slow, off when not needed. Overlay and main UI are two views of the same data set; behavior (staleness, precision, data source) should be consistent across both.
 </domain>
 <decisions>
 ## Implementation Decisions
 ### Background transitions
 - When app backgrounds WITHOUT overlay visible: GPS stops after a short grace period (5-10 seconds), not immediately
 - Grace period allows brief app-switching (checking a notification) without losing GPS fix
 - When returning to foreground after GPS stopped: show last known speed until fresh data arrives (feels instant, briefly stale)
 - When app backgrounds WITH overlay visible: full GPS precision at all times, no power-saving reduction
 - User chose overlay = deliberate commitment to battery cost
 ### Precision change visibility
 - GPS precision switching (high/balanced) is completely invisible to the user
 - No indicators, no UI changes -- speed and heading just work
 - Precision transitions logged for debug purposes only
 - User-visible surface is speed (with units) and heading (with compass direction) -- nothing else
 - Accuracy readout is debug-only territory
 ### Main app staleness
 - Apply same staleness detection to main speed display as overlay: 3s dim, 10s dashes, immediate snap-back
 - Overlay and main UI are two presentations of the same data -- same staleness rules apply to both
 - This is a NEW behavior for the main app (overlay already has it from Phase 3)
 ### Power priority tradeoffs
 - Near the speed threshold (8-12 km/h hysteresis zone): favor accuracy over battery
 - When in doubt, stay in high precision mode rather than dropping to balanced
 - Battery saver mode: respect it partially -- use balanced precision always (skip high mode), but still track
 - Foreground GPS: stays on indefinitely while app is visible, no idle timeout. User closes the app when done.
 - Wake lock: keep screen awake for BOTH overlay background tracking AND main app when GPS is actively tracking (dashboard use case)
 - Wake lock expansion: PWR-05 requirement updated from "overlay only" to "overlay + main app foreground"
 ### Claude's Discretion
 - Timer architecture: whether background grace period (5-10s) reuses Phase 3's existing grace period timer infrastructure or stays separate
 - Exact grace period duration within the 5-10s range
 - Debug logging format and verbosity for precision transitions
 - How staleness detection is shared between main app and overlay (shared utility vs duplicated logic)
 </decisions>
 <specifics>
 ## Specific Ideas
 - "Overlay and main UI are two ways of displaying the same data set" -- high-level architectural principle. Same data source, same staleness, same behavior rules.
 - Dashboard mounting use case: wake lock keeps screen on while actively tracking, whether using main app or overlay
 - Battery saver as a soft constraint, not a hard override: the app still functions, just at reduced precision
 </specifics>
 <deferred>
 ## Deferred Ideas
 None -- discussion stayed within phase scope
 </deferred>
 ---
 *Phase: 04-gps-power-optimization*
 *Context gathered: 2026-02-12*