mobile-ai-agents 1.0.23

package/agents/android/android-crash-analyzer/README.md

@@ -0,0 +1,134 @@
+# Android Crash Analyzer Agent
+
+> Paste a crash log. Get a root-cause analysis, a production-ready fix, and a testing checklist — in seconds.
+
+---
+
+## What This Agent Does
+
+The Android Crash Analyzer reads raw crash logs, ANR traces, and Firebase Crashlytics exports and returns a structured 9-section report:
+
+1. **Crash Summary** — type, severity, reproducibility
+2. **Root Cause** — what actually went wrong, not just which line
+3. **Why This Happens** — plain-English explanation for any team member
+4. **Risk Level** — Critical / High / Medium / Low + affected user estimate
+5. **Recommended Fix** — step-by-step, lifecycle-aware solution
+6. **Updated Code** — before/after Kotlin snippets with inline comments
+7. **Edge Cases** — other places the same bug can hide
+8. **Testing Checklist** — concrete steps to verify the fix
+9. **Prevention Tips** — architecture, lint rules, tooling
+
+---
+
+## Supported Crash Types
+
+| Category | Examples |
+|---|---|
+| Null & Type | NullPointerException, ClassCastException, IllegalArgumentException |
+| Lifecycle | Fragment not attached, Activity after finish(), View after onDestroyView |
+| Concurrency | GlobalScope leak, UI update off main thread, race condition on shared state |
+| Coroutines | Unhandled exception, wrong dispatcher, missing CoroutineExceptionHandler |
+| RecyclerView | Invalid adapter position, DiffUtil conflict, view holder type mismatch |
+| Memory | OOM from bitmap, leak from static context reference, Handler not cleared |
+| ANR | Main thread blocked by I/O, lock contention, broadcast timeout |
+| Firebase / Crashlytics | Symbolicated and unsymbolicated exports |
+| Custom | Any stack trace you paste — the agent infers the crash type |
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| [`agent.md`](agent.md) | Full agent spec: input format, output format, system prompt |
+| [`example-input.md`](example-input.md) | Real Android crash log ready to paste |
+| [`example-output.md`](example-output.md) | Full 9-section analysis of that crash |
+
+---
+
+## Quick Start
+
+### Claude Code
+
+```
+# In your Claude Code session:
+Use the system prompt from agents/android/android-crash-analyzer/agent.md
+Then paste the input from example-input.md — or replace it with your own crash log.
+```
+
+### ChatGPT / Cursor
+
+1. Open `agent.md`
+2. Copy the **System Prompt** section
+3. Paste it as your first message
+4. Follow with your crash log using the input format
+
+### Cursor `.cursorrules`
+
+The agent rules are already loaded via `.cursorrules` at the repo root. In Cursor Chat:
+
+```
+@agents/android/android-crash-analyzer/agent.md
+Analyze this crash: [paste log]
+```
+
+---
+
+## Input Format
+
+```
+PLATFORM: Android
+APP_VERSION: <version>
+OS_VERSION: <Android version>
+DEVICE: <device model>
+USER_ACTION: <what the user was doing>
+CRASH_LOG:
+<full stack trace or ANR trace>
+RELATED_CODE: <optional — paste the code around the crash site>
+```
+
+---
+
+## Output Example
+
+See [`example-output.md`](example-output.md) for the full 9-section report.
+
+**Preview:**
+
+```
+## Crash Summary
+IllegalStateException in ProfileFragment.kt:88 when a coroutine posts to a
+LiveData observer after the Fragment is detached. HIGH severity — reproducible
+on slow networks when the user navigates back during a request.
+
+## Root Cause
+viewModelScope survives the Fragment's view lifecycle. When the coroutine
+completes and sets _profile.value, the LiveData observer fires. By then,
+requireContext() throws because the Fragment has no attached context.
+```
+
+---
+
+## Best Practices
+
+- Paste the **full** stack trace — truncated traces miss the first app frame
+- Include `USER_ACTION` — it is the single most useful field for lifecycle crashes
+- For Firebase exports, paste the full event (not just the stack) — metadata matters
+- For ANR traces, paste the complete `traces.txt` file from `/data/anr/`
+- For LeakCanary output, paste the full reference chain
+
+---
+
+## Related Agents
+
+- [`agents/android/code-reviewer`](../code-reviewer/) — pre-crash code quality review
+- [`agents/android/compose-ui-reviewer`](../compose-ui-reviewer/) — Compose-specific issues
+- [`agents/ios/crash-analyzer`](../../ios/crash-analyzer/) — same workflow for iOS
+
+---
+
+## Contributing
+
+Found a crash type this agent handles poorly? Open an issue using the
+[Bug Report template](../../../.github/ISSUE_TEMPLATE/bug_report.md) and paste the
+anonymized crash log. We'll improve the system prompt and add it as a new example.

package/agents/android/android-crash-analyzer/agent.md

@@ -0,0 +1,206 @@
+# Agent — Android Crash Analyzer
+
+**Platform:** Android (Kotlin / Java)  
+**Category:** Debugging & Crash Analysis  
+**Complexity:** Medium  
+**Tested With:** Claude Sonnet 4.6, GPT-4o, Gemini 1.5 Pro
+
+---
+
+## Purpose
+
+Analyzes Android crash logs, ANR traces, Firebase Crashlytics exports, and LeakCanary reports to produce a structured root-cause analysis with a production-ready fix, before/after code, edge-case coverage, a concrete testing checklist, and prevention tips.
+
+---
+
+## Supported Crash Types
+
+- `NullPointerException` — null reference, async result used before load
+- `IllegalStateException` — Fragment not attached, invalid state machine transition
+- `IllegalArgumentException` — bad parameter, mismatched View IDs
+- `IndexOutOfBoundsException` — list modified during iteration, RecyclerView position
+- `ClassCastException` — wrong ViewHolder type, mismatched Parcelable
+- `OutOfMemoryError` — bitmap cache, retained context, large allocation
+- `StackOverflowError` — recursive composable, infinite recomposition trigger
+- `ANR (Application Not Responding)` — main thread blocked by I/O, lock, or broadcast
+- Coroutine crashes — unhandled exception in `launch { }`, wrong dispatcher
+- ViewModel observer bugs — duplicate observers, observer after `onDestroyView`
+- RecyclerView crashes — `RecyclerView.NO_ID`, async list update conflict
+- Memory leaks — LeakCanary reference chains, static Activity context
+
+---
+
+## Input Format
+
+```
+PLATFORM: Android
+APP_VERSION: <e.g. 4.1.2 (build 314)>
+OS_VERSION: <e.g. Android 14 — API 34>
+DEVICE: <e.g. Samsung Galaxy S24 Ultra>
+USER_ACTION: <what the user was doing when the crash occurred>
+CRASH_LOG:
+<paste the full logcat output, Firebase Crashlytics export, ANR trace, or LeakCanary report>
+RELATED_CODE:
+<optional — paste the Kotlin/Java code at or near the crash site>
+```
+
+**Field notes:**
+
+| Field | Required | Notes |
+|---|---|---|
+| `PLATFORM` | Yes | Always `Android` |
+| `APP_VERSION` | Yes | Correlate with release history |
+| `OS_VERSION` | No | Narrows OS-specific and API-level bugs |
+| `DEVICE` | No | Narrows OEM-specific bugs (Samsung, Xiaomi, etc.) |
+| `USER_ACTION` | Yes | The single most useful field for lifecycle crashes |
+| `CRASH_LOG` | Yes | Full output — never truncate |
+| `RELATED_CODE` | No | Speeds up analysis; paste the class around the crash line |
+
+---
+
+## Output Format
+
+The agent always returns exactly these 9 sections, in order:
+
+```
+## Crash Summary
+## Root Cause
+## Why This Happens
+## Risk Level
+## Recommended Fix
+## Updated Code
+## Edge Cases
+## Testing Checklist
+## Prevention Tips
+```
+
+### Section Definitions
+
+**## Crash Summary**  
+2–3 sentences. Crash type, where it happened, severity, reproducibility.
+
+**## Root Cause**  
+Precise technical explanation. Not just the crashing line — the sequence of events and state that led to it.
+
+**## Why This Happens**  
+Plain-English explanation for any developer on the team, including juniors. Analogies encouraged.
+
+**## Risk Level**  
+One of: `CRITICAL` / `HIGH` / `MEDIUM` / `LOW`  
+Include reproducibility (`Always` / `Intermittent` / `Rare`) and an affected-user estimate if volume data is provided.
+
+**## Recommended Fix**  
+Step-by-step. Every step is a concrete code change, not vague advice. Prefer lifecycle-aware patterns.
+
+**## Updated Code**  
+```kotlin
+// Before — problematic code with the issue annotated
+...
+
+// After — corrected code with inline comments explaining key decisions
+...
+```
+
+**## Edge Cases**  
+Bullet list of other scenarios where the same root cause could appear — beyond the specific crash site.
+
+**## Testing Checklist**  
+Checkboxes. Each step is a specific scenario a developer can reproduce manually or automate.
+
+**## Prevention Tips**  
+Architectural practices, lint rules, static analysis tools, and code review items that prevent this crash class from recurring.
+
+---
+
+## System Prompt
+
+```
+You are a senior Android crash debugging agent with deep expertise in Kotlin, Java,
+Android lifecycle, Jetpack Architecture Components (ViewModel, LiveData, Navigation),
+Jetpack Compose, Coroutines, Flow, RecyclerView, Room, Hilt, and Firebase Crashlytics.
+
+Your job is to analyze Android crash logs and related code exactly as an experienced
+Android principal engineer would in a production incident post-mortem.
+
+ANALYSIS PROCESS:
+1. Identify the exception type or signal (NPE, ISE, ANR, OOM, coroutine exception, etc.)
+2. Find the FIRST APPLICATION FRAME — skip all system frames:
+   android.*, java.*, kotlin.*, kotlinx.*, androidx.*, com.google.*
+   The first frame with the app's package name is the origin.
+3. Read the call chain from bottom (entry point) to top (crash site).
+4. Identify the USER ACTION or lifecycle event that started the chain.
+5. Determine the ROOT CAUSE — not just the faulting line, but WHY that state was reached.
+6. Write a plain-English explanation (Why This Happens) suitable for a junior developer.
+7. Produce the safest, most lifecycle-aware fix — never suggest workarounds that mask bugs.
+8. Write BEFORE/AFTER Kotlin code with inline comments on every non-obvious line.
+9. List EDGE CASES — other places in a typical codebase where the same root cause hides.
+10. Write a TESTING CHECKLIST with specific, reproducible steps.
+11. Add PREVENTION TIPS — lint rules, architecture patterns, tooling.
+
+PLATFORM-SPECIFIC RULES:
+
+Fragment / Activity lifecycle:
+- requireContext() / requireActivity() throws if Fragment is not attached
+- Accessing views after onDestroyView() causes NPE (ViewBinding not nulled out)
+- registering observers in onViewCreated() without removing them accumulates duplicates
+  across configuration changes if the LifecycleOwner used is the Fragment (not viewLifecycleOwner)
+
+Coroutines:
+- GlobalScope is ALWAYS wrong in Android — use viewModelScope or lifecycleScope
+- launch { } without try/catch or CoroutineExceptionHandler silently crashes the coroutine
+- Posting to LiveData/StateFlow from a non-Main dispatcher crashes with CalledFromWrongThreadException
+- Cancellation exceptions must NOT be caught generically — use catch (e: Exception) { if (e is CancellationException) throw e }
+
+RecyclerView:
+- Accessing adapter.getItem(position) inside an onClick that fires after async list update = IOOB
+- ViewHolder types must match: onCreateViewHolder returns type T, onBindViewHolder binds to T
+- DiffUtil running async while adapter is replaced = inconsistency crash
+
+Memory:
+- Static reference to Context, View, or Activity = guaranteed leak
+- Inner class (non-static) holds implicit reference to outer Activity
+- Handler posted with postDelayed holds a reference chain to Activity
+
+ANR:
+- ANY disk/network I/O on the main thread, even tiny reads, can ANR under load
+- Broadcast receivers have a 10-second execution budget on the main thread
+- ContentProvider.query() on the main thread blocks the UI
+
+RULES:
+- Never guess without stating the assumption explicitly
+- If information is missing from the log, state exactly what is missing and what to collect
+- Prefer Kotlin null-safety (?., ?:, let, run) over !! or defensive null checks
+- Prefer repeatOnLifecycle(STARTED) + StateFlow over LiveData observers in new code
+- For coroutine issues: always check scope, dispatcher, exception handling, and cancellation
+- Production fixes must be safe to ship without hotfix risk
+
+OUTPUT MUST follow the exact 9-section structure:
+Crash Summary | Root Cause | Why This Happens | Risk Level | Recommended Fix |
+Updated Code | Edge Cases | Testing Checklist | Prevention Tips
+
+Do not add extra sections. Do not omit any section. If a section has nothing relevant
+(e.g., no related code for Updated Code), explain why and skip the code block.
+```
+
+---
+
+## Best Practices for Users
+
+1. **Paste the full stack trace.** Every line matters. Truncated logs miss the origin frame.
+2. **Always fill `USER_ACTION`.** "The user tapped the back button while the image was uploading" is worth 10 lines of code.
+3. **Include the `RELATED_CODE` field** when you already know which class is crashing — the agent produces far more accurate `Updated Code` output.
+4. **For Firebase Crashlytics:** Export the full event JSON, not just the stack. The OS version, memory state, and session ID narrow the root cause significantly.
+5. **For ANR:** Paste the complete `traces.txt` dump. A single-thread excerpt hides the blocking call.
+6. **For LeakCanary:** Paste the full reference chain, not just the leaked object.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Effect | Solution |
+|---|---|---|
+| Pasting only the exception line | Agent can't trace the call chain | Paste the full stack including thread header |
+| Omitting `USER_ACTION` | Lifecycle analysis is guesswork | Always describe what the user was doing |
+| Truncating after 20 lines | Cuts the origin frame | Paste everything |
+| Pasting unsymbolicated NDK crash | Hex addresses are unresolvable | Symbolicate first with `ndk-stack` or Firebase |
+| Using `try?` in a workaround | Hides the real bug | Fix the root cause; don't silence exceptions |

package/agents/android/android-crash-analyzer/example-input.md

@@ -0,0 +1,138 @@
+# Example Input — Android Crash Analyzer
+
+This is a real-world crash scenario. Paste this into your LLM session after applying the system prompt from `agent.md`, or replace the `CRASH_LOG` and `RELATED_CODE` sections with your own.
+
+---
+
+```
+PLATFORM: Android
+APP_VERSION: 3.7.1 (build 412)
+OS_VERSION: Android 13 — API 33
+DEVICE: Google Pixel 7
+USER_ACTION: User tapped the back button while the profile photo was uploading. The upload progress dialog was still visible when they navigated back.
+
+CRASH_LOG:
+Fatal Exception: java.lang.IllegalStateException: Fragment ProfileFragment{3a1b2c3} (b4c5d6e7-f8a9-0b1c-2d3e-4f5a6b7c8d9e) not attached to a context.
+	at androidx.fragment.app.Fragment.requireContext(Fragment.java:947)
+	at com.example.socialapp.ui.profile.ProfileFragment.showUploadSuccess(ProfileFragment.kt:124)
+	at com.example.socialapp.ui.profile.ProfileFragment$observeViewModel$1.onChanged(ProfileFragment.kt:89)
+	at androidx.lifecycle.LiveData.considerNotify(LiveData.java:133)
+	at androidx.lifecycle.LiveData.dispatchingValue(LiveData.java:151)
+	at androidx.lifecycle.LiveData.setValue(LiveData.java:309)
+	at androidx.lifecycle.MutableLiveData.setValue(MutableLiveData.java:50)
+	at androidx.lifecycle.LiveData$1.run(LiveData.java:91)
+	at android.os.Handler.handleMessage(Handler.java:942)
+	at android.os.Looper.loopOnce(Looper.java:201)
+	at android.os.Looper.loop(Looper.java:288)
+	at android.app.ActivityThread.main(ActivityThread.java:7872)
+	at java.lang.reflect.Method.invoke(Method.java)
+	at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:548)
+	at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:936)
+
+RELATED_CODE:
+// ProfileFragment.kt
+class ProfileFragment : Fragment(R.layout.fragment_profile) {
+
+    private val viewModel: ProfileViewModel by viewModels()
+    private var _binding: FragmentProfileBinding? = null
+    private val binding get() = _binding!!
+
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        super.onViewCreated(view, savedInstanceState)
+        _binding = FragmentProfileBinding.bind(view)
+
+        viewModel.uploadState.observe(this) { state ->   // line 89 — observing with 'this' not viewLifecycleOwner
+            when (state) {
+                is UploadState.Success -> showUploadSuccess(state.photoUrl)
+                is UploadState.Error   -> showError(state.message)
+                else -> Unit
+            }
+        }
+
+        binding.uploadButton.setOnClickListener {
+            viewModel.uploadPhoto(requireContext(), getSelectedBitmap())
+        }
+    }
+
+    private fun showUploadSuccess(photoUrl: String) {
+        val ctx = requireContext()   // line 124 — throws if Fragment is detached
+        Snackbar.make(ctx, binding.root, "Photo updated!", Snackbar.LENGTH_SHORT).show()
+        Glide.with(ctx).load(photoUrl).into(binding.avatarImage)
+    }
+
+    override fun onDestroyView() {
+        super.onDestroyView()
+        _binding = null
+    }
+}
+
+// ProfileViewModel.kt
+class ProfileViewModel @Inject constructor(
+    private val photoRepository: PhotoRepository
+) : ViewModel() {
+
+    private val _uploadState = MutableLiveData<UploadState>()
+    val uploadState: LiveData<UploadState> = _uploadState
+
+    fun uploadPhoto(context: Context, bitmap: Bitmap) {
+        viewModelScope.launch {
+            _uploadState.value = UploadState.Loading
+            try {
+                val url = photoRepository.uploadPhoto(context, bitmap)
+                _uploadState.value = UploadState.Success(url)
+            } catch (e: Exception) {
+                _uploadState.value = UploadState.Error(e.message ?: "Upload failed")
+            }
+        }
+    }
+}
+```
+
+---
+
+## What to Expect
+
+Running this input through the crash analyzer agent produces a full 9-section report. See [`example-output.md`](example-output.md) for the complete analysis.
+
+**Key issues the agent should identify:**
+
+1. Observer registered with `this` (Fragment) instead of `viewLifecycleOwner` — accumulates duplicate observers across configuration changes and fires after the view is destroyed
+2. `requireContext()` called inside an observer callback that can fire after the Fragment is detached
+3. `Context` passed into `ViewModel.uploadPhoto()` — the ViewModel holds a `Context` reference, creating a memory leak
+4. No `UploadState.Loading` UI feedback cancellation when the user navigates away mid-upload
+
+---
+
+## Variations to Try
+
+Replace the crash log to test other scenarios:
+
+### ANR Scenario
+```
+USER_ACTION: App was open on the home screen. User did nothing for 10 seconds.
+CRASH_LOG:
+ANR in com.example.socialapp (com.example.socialapp/.ui.home.HomeActivity)
+PID: 12345
+Reason: Input dispatching timed out (Waiting to send non-key input event because the touched window has not finished processing certain input events that were delivered to it over 500.0ms ago.  Wait queue length: 2.  Wait queue head age: 8510.2ms.)
+...
+----- pid 12345 at 2025-05-29 10:30:45 -----
+Cmd line: com.example.socialapp
+
+"main" prio=5 tid=1 Blocked
+  | group="main" sCount=1 dsCount=0 flags=1 obj=0x71a2b3c4 self=0x71a2b3c5
+  | sysTid=12345 nice=-10 cgrp=top-app sched=0/0 handle=0x71a2b3c6
+  at com.example.socialapp.data.local.AppDatabase.query(AppDatabase.kt:0)
+  - waiting to lock <0x0a1b2c3d> (a com.example.socialapp.data.local.AppDatabase) held by thread 2
+  at com.example.socialapp.ui.home.HomeViewModel$loadFeed$1.invokeSuspend(HomeViewModel.kt:45)
+```
+
+### Coroutine Crash Scenario
+```
+USER_ACTION: User refreshed the feed by pulling down.
+CRASH_LOG:
+Fatal Exception: kotlinx.coroutines.JobCancellationException: StandaloneCoroutine was cancelled
+Caused by: java.net.UnknownHostException: Unable to resolve host "api.socialapp.com": No address associated with hostname
+	at com.example.socialapp.data.remote.FeedApi.getFeed(FeedApi.kt:0)
+	at com.example.socialapp.data.repository.FeedRepository.refreshFeed(FeedRepository.kt:38)
+	at com.example.socialapp.ui.home.HomeViewModel$refresh$1.invokeSuspend(HomeViewModel.kt:52)
+```