# Intent-vs-Reality Review **Purpose:** Find all places where documented intent, comments, or code-map descriptions diverge from what the code actually does. Run this whenever a significant refactor lands, before merging a long-running branch, or whenever a regression reveals a code-map inaccuracy. **How to run:** paste the prompt below into a new agent session with access to the repo. It is intentionally exhaustive — expect 30–60 min of analysis. --- ## Prompt You are auditing the Nav Android codebase for gaps between **documented intent** and **implemented reality**. A gap is any case where a comment, doc file, code-map entry, or TODO describes behavior that differs from what the code actually does. Work through each category below. For each finding, report: - **File and line** (or doc file + section) - **What it claims** (quote the doc/comment) - **What the code does** (cite the relevant lines) - **Severity**: `MISLEADING` (wrong, will cause future bugs), `STALE` (was true, no longer is), or `ASPIRATIONAL` (planned but not built) ### Category 1 — Code-map vs implementation Read `.agent/code-map.md` sections 3 (Source Package Map) and 8 (Context Tips & Gotchas). For every class or behavior mentioned: 1. Verify the class exists at the stated path. 2. Verify the described role matches the actual implementation. 3. Flag any class listed with a role that has been superseded or is dead code. Pay special attention to: - Classes listed under `gps/` — `DeviceGpsProvider` has historically been misrepresented - The "Navigation / GPS" gotcha section — descriptions of flow and staleness behavior - Any mention of flows, StateFlows, or SharedFlows — check `replay` values and whether subscribers actually receive stale data - Any mention of UI features (banners, dialogs, buttons) — verify they exist in layouts and are wired up ### Category 2 — Dead code with documented intent Search for code that is defined but never instantiated or called. These represent features that were planned, partially built, or left behind after a refactor: 1. Run: find all classes implementing an interface — check if any implementation is never constructed anywhere (grep for `= MyClass(` and `MyClass(` across all Kotlin files). 2. Look specifically at: - `gps/GpsProvider.kt` and its implementations - Any `Handler` with a posted `Runnable` that looks like a timeout/watchdog - Any `companion object` constant named `*_TIMEOUT_MS` or `*_THRESHOLD_MS` — verify the timeout is actually used 3. For each dead class/method, check git log to understand if it was once wired up and was removed in a refactor (use `git log --all -S 'ClassName'` to find commits that removed references). ### Category 3 — Comments that describe the wrong behavior Scan for inline comments that assert behavior (`// GPS updates every 1 Hz`, `// always fresh`, `// cleared on pause`, `// foreground only`, etc.) and verify the code around them matches the claim: 1. Search for `// TODO` entries — for each one, determine if the TODO was actually completed elsewhere (the code may have been fixed but the comment not removed). 2. Search for comments referencing specific class names, method names, or behaviors — verify those classes/methods/behaviors still exist with the described properties. 3. Look for comments in `MainActivity.kt`, `LocationService.kt`, and `MainViewModel.kt` specifically — these are the highest-churn files. ### Category 4 — Architectural invariants not enforced Read `.agent/code-map.md` section 5 (Key Architectural Invariants). For each invariant: 1. Verify the invariant holds in the current code. 2. If it was intended to be enforced by a specific mechanism (e.g., `@Synchronized`, a guard variable, a specific flow), verify that mechanism is actually in place. 3. Flag any invariant that is stated as a rule but has no enforcement — these are regression risks. Current invariants to check: - Track storage source-of-truth = GPX/SAF (Room is read-cache only) - `getExternalFilesDir()` never used for user data - `NavLogger` as primary debug tool (not just Android `Log`) - MOB button always visible and non-dismissible - `InMemoryLogbookRepository` has `@Synchronized` on save/getAll/reload - `VoiceLogFragment` passes both `onSelect` and `onReport` to `SavedTrackAdapter` - MapLibre speed-color uses `Expression.step()` not `Expression.get("color")` - NMEA wind data is apparent, converted to true in `PerformanceViewModel` - All display values go through `UnitPrefs` ### Category 5 — Design doc vs shipped code Read `.agent/design.md`. For any feature described as "implemented" or in a "completed" state: 1. Verify the feature exists in the code. 2. Verify the implementation matches the described design (API shape, data flow, UI layout). 3. Flag features described as in-progress that appear to have been abandoned without a code-map update. ### Category 6 — Worklog vs current state Read `.agent/worklog.md` section "Recently Completed". For each completed item: 1. Spot-check that the described change is actually present in the code. 2. Look for cases where a "completed" item was later reverted or partially undone by a subsequent merge (use `git log --all --oneline -- ` to trace history). --- ## Output format Group findings by category. Use this structure: ``` ## [Category N] — [Category name] ### Finding: [short title] - **Doc claim**: "[exact quote]" — `file:line` - **Code reality**: [what the code actually does] — `file:line` - **Severity**: MISLEADING / STALE / ASPIRATIONAL - **Suggested fix**: [one sentence — update the doc, delete the dead code, or implement the feature] ``` End with a **Summary** section: total findings by severity, and the top 3 highest-risk gaps (most likely to cause future bugs or agent confusion). --- ## After the review For each `MISLEADING` finding: fix the code-map or comment immediately in the same session. Do not leave the session with any known-wrong documentation. For `ASPIRATIONAL` findings: add a note to `.agent/worklog.md` backlog if the feature is still wanted, or delete the dead code if it is not. For `STALE` findings: update the documentation to match current reality. Commit all documentation fixes as a single commit: `"docs(agent): intent-reality audit — correct N misleading entries"`.