Maintenance & Bug Fixing

Guidelines for triaging, debugging, and resolving production issues (Bugs, ANRs, Regressions) safely.

1. Bug Fixing Protocol (AI & Developer Workflow)

When implementing a fix or addressing an issue, strict adherence to the following sequence is mandatory. Do not make any assumptions, fail out loud, and ask for clarity.

1. Information Gathering: Completely gather all necessary data before touching code. Ask the user for crash logs, system traces, or screenshots if they are required. The user can provide system traces for code if needed.
2. Analysis: Analyze the codebase deeply and identify the accurate, root-cause fix.
3. Preview (Diff Style): Propose the change to the user using a diff style format (or via an implementation_plan.md artifact). Clearly state the class name and function being modified.
4. Approval & Execution: Do not apply corrections until explicit approval is given by the user. Once approved, apply the exact changes.
5. Post-Correction Review: After applying the fix, show the resulting code changes using a diff style summary to confirm the exact modifications made.
6. Verification: Ask the user to check the fix on a physical device. Only mark the task as completed after on-device verification is successful.

2. Triage & Investigation

• Trace the Source: When presented with a stack trace (e.g., from Firebase Crashlytics), isolate the specific layer. Is it a UI crash? A background service exception? A location permission denial?
• Avoid Guesswork: Do not blindly wrap code in try/catch. Find the root cause (e.g., NullPointerException because GPS returned null before lock-on).

2. Fixing Application Not Responding (ANRs)

ANRs occur when the Main (UI) thread is blocked for > 5 seconds.

• Rule: Never perform I/O, database reads (Room/DataStore), or heavy computation (like filtering GPS arrays) on the Main thread.
• Fix: Move heavy work to Dispatchers.IO or Dispatchers.Default using Coroutines.

  withContext(Dispatchers.Default) {
      // heavy GPS math
  }

3. The Regression Testing Rule

Before fixing any reported bug, you must write a failing test that reproduces the bug.

1. Write a Unit Test that mimics the conditions of the crash. It should fail.
2. Implement the fix in the codebase.
3. Run the test again. It should pass. This ensures the bug is caught in CI/CD and never returns.

4. Safe Refactoring

When modernizing legacy code (e.g., migrating an old XML Activity to Compose or refactoring the SpeedometerService):

• Isolate: Extract the business logic from the Android component into a decoupled class first.
• Test: Write tests for the decoupled logic.
• Replace: Swap the old implementation for the new one. Ensure zero functional changes from the user's perspective unless explicitly requested.