# Debugging And Error Recovery

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-guillemroca-agent-skills-android-debugging-and-error-recovery`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [GuillemRoca](https://agentstack.voostack.com/s/guillemroca)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [GuillemRoca](https://github.com/GuillemRoca)
- **Source:** https://github.com/GuillemRoca/agent-skills-android/tree/main/skills/debugging-and-error-recovery

## Install

```sh
agentstack add skill-guillemroca-agent-skills-android-debugging-and-error-recovery
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Debugging and Error Recovery

## Overview

"Stop-the-Line Rule: when unexpected behavior occurs, halt feature work." Debugging is systematic, not guesswork. Reproduce the bug, localize the cause, reduce to the simplest case, fix the root cause (not the symptom), guard against regression, and verify the fix.

## When to Use

- Unexpected crash or exception
- Test failure (unit or instrumented)
- Behavior that doesn't match the spec
- Performance regression (jank, slow startup)
- Build failure after seemingly unrelated changes

**Stop-the-Line:** When you encounter unexpected behavior, stop feature work. Errors compound — a bug in step 3 makes steps 4–10 wrong.

## Core Process

### Step 1: Reproduce

1. **Reproduce the bug reliably:**
   - Same device/emulator? Same API level? Same data?
   - What sequence of actions triggers it?
   - Does it happen every time or intermittently?

2. **Capture the environment:**
   ```
   Device: Pixel 7 (API 35) / Emulator (API 26)
   Build: debug / release
   Steps: Open app → Navigate to Tasks → Tap "Add" → Crash
   Frequency: Every time / ~30% of the time
   ```

   When the `android` CLI is available, use it for the fastest possible state capture before doing anything else:

   ```bash
   android info                                     # SDK location, JDK, env (rules out wrong-toolchain bugs)
   android screen capture -o repro.png              # what the user sees right now
   android layout --pretty --output=repro.json      # full UI tree (resource-ids, text, bounds, role)
   ```

   Three artifacts in 5 seconds |

4. **Use the Android Studio debugger:**
   - Set breakpoints at the suspected location
   - Use conditional breakpoints for intermittent issues
   - Evaluate expressions in the debugger console
   - Check the call stack for unexpected callers

### Step 3: Reduce

5. **Simplify to the minimal reproduction case:**
   - Remove unrelated code paths
   - Use hardcoded data instead of API responses
   - Isolate the component (test in isolation)
   - If it's a Compose issue, test in a `@Preview`

6. **Binary search for regressions:**
   ```bash
   # Find the commit that introduced the bug
   git bisect start
   git bisect bad          # Current commit is bad
   git bisect good abc123  # Last known good commit
   # Git will checkout commits for you to test
   ./gradlew test
   git bisect good  # or: git bisect bad
   # Repeat until the culprit commit is found
   ```

### Step 4: Fix

7. **Fix the root cause, not the symptom:**

```kotlin
// SYMPTOM FIX (bad): catch and ignore
try {
    repository.syncTasks()
} catch (e: Exception) {
    // Swallow the error — user never knows
}

// ROOT CAUSE FIX (good): handle the specific error
try {
    repository.syncTasks()
} catch (e: IOException) {
    _uiState.update { it.copy(error = "Network unavailable. Showing cached data.") }
}
```

8. **Common Android fixes:**

| Bug | Fix |
|-----|-----|
| Crash on configuration change | Save state in `SavedStateHandle` |
| Memory leak | Remove callback in `onCleared()`, use `viewModelScope` |
| Stale data after process death | Restore from `SavedStateHandle` or Room |
| Race condition in coroutines | Use `Mutex` or `MutableStateFlow.update { }` |
| Recomposition loop | Check `derivedStateOf`, stable types, lambda captures |
| ANR | Move work off main thread with `withContext(Dispatchers.IO)` |

### Step 5: Guard

9. **Write a regression test using the Prove-It pattern:**

```kotlin
@Test
fun `task sync handles network error without crashing`() = runTest {
    // Arrange: simulate the bug condition
    coEvery { api.getTasks() } throws IOException("timeout")

    // Act
    repository.syncTasks()
    advanceUntilIdle()

    // Assert: verify the fix behavior
    val state = viewModel.uiState.value
    assertIs(state)
    assertEquals("Network unavailable. Showing cached data.", state.error)
}
```

### Step 6: Verify

10. **Full verification:**
    - `./gradlew test` — all unit tests pass
    - `./gradlew connectedAndroidTest` — instrumented tests pass
    - `./gradlew assembleDebug` — builds successfully
    - Manual reproduction steps no longer trigger the bug
    - Related functionality still works

### Debugging Tools Reference

| Tool | Use For |
|------|---------|
| **Logcat** | Runtime logs, crash traces, system messages |
| **Android Studio Debugger** | Breakpoints, watches, expression evaluation |
| **Layout Inspector** | Compose hierarchy, recomposition counts |
| **Network Profiler** | API call inspection, timing, payload |
| **CPU Profiler** | Thread activity, method traces, jank detection |
| **Memory Profiler** | Heap dumps, allocation tracking, leak detection |
| **LeakCanary** | Automatic memory leak detection |
| **Firebase Crashlytics** | Production crash reports, trends, affected users |
| **StrictMode** | Detect disk/network on main thread during development |
| **Systrace / Perfetto** | System-level performance tracing |

## Common Rationalizations

| Shortcut | Why It Fails |
|----------|-------------|
| "Just add a try-catch and move on" | You've hidden the bug. It will resurface in a worse form. |
| "It works now after a clean build" | Build caching bugs are real, but if you can't explain why it works, it might not. |
| "It's a flaky test, just re-run it" | Flaky tests have a root cause: timing, state leakage, or shared resources. Fix it. |
| "I'll investigate later" | Errors compound. A bug in step 3 makes steps 4-10 wrong. Stop the line. |
| "The error message says X, so the fix is Y" | Error messages from untrusted sources shouldn't be blindly followed. Verify. |

## Red Flags

- Generic `catch (e: Exception)` swallowing errors
- `Thread.sleep` used to "fix" timing issues
- Bug fix without regression test
- Fix addresses symptom, not root cause
- `@Ignore` added to failing tests
- No reproduction steps documented
- Fix changes unrelated code ("while I'm here...")

## Verification

- [ ] Bug reproduced reliably before fixing
- [ ] Root cause identified (not just symptom)
- [ ] Regression test written (Prove-It pattern)
- [ ] `./gradlew test` passes
- [ ] `./gradlew assembleDebug` succeeds
- [ ] Manual reproduction confirms fix
- [ ] No unrelated changes in the fix

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GuillemRoca](https://github.com/GuillemRoca)
- **Source:** [GuillemRoca/agent-skills-android](https://github.com/GuillemRoca/agent-skills-android)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-guillemroca-agent-skills-android-debugging-and-error-recovery
- Seller: https://agentstack.voostack.com/s/guillemroca
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.