Here is a compact terminal workflow for a debug app. Each step answers a question rather than adding another command to memorize.

Before you start

Examples use macOS/Linux shell syntax, an app module, and a debug variant. On Windows, use gradlew.bat and adapt shell variables and quoting. Run Gradle commands from the project root. Your configured JDK must be compatible with the project's Android Gradle Plugin.

Have SDK Platform Tools on your PATH and an authorized test device or emulator connected:

adb devices -l
export ANDROID_SERIAL=emulator-5554

Replace the serial with one from the output. ANDROID_SERIAL selects the target for subsequent ADB commands. An unauthorized device needs approval on the unlocked device.

1. Can someone else build this exact variant?

Use the project's Gradle Wrapper:

./gradlew :app:assembleDebug

For a conventional project, the APK is at app/build/outputs/apk/debug/app-debug.apk. Flavors and output customization change tasks and paths; inspect the actual project:

./gradlew :app:tasks --all

For a flavor named demo, look for assembleDemoDebug. A successful build produces an artifact; it doesn't mean the app was installed or launched. These task conventions are described in the Android command-line build guide.

2. Is the build on the intended device?

adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -W -n com.example.debugcli/.MainActivity

Replace the application ID and activity with your debug variant's actual values. -r replaces an installed compatible package while retaining its data. A signature mismatch needs investigation; deleting an app is not a neutral fix because it removes local data.

Alternatively, ./gradlew :app:installDebug builds and installs. Check its output to confirm the selected device or devices when several are connected. See the ADB guide.

3. Which logs belong to the running process?

After launching the app, get its current PID:

adb shell pidof -s com.example.debugcli

Suppose it prints 12345. Use that value:

adb logcat --pid=12345 -v threadtime

Stop streaming with Ctrl+C. An empty PID usually means the process isn't running or the application ID is wrong. Recheck it after a restart: a new process can have a new PID. Separate app processes need separate consideration.

A PID filter is focused, but can hide useful system-side evidence. For crash investigation, also inspect the crash buffer:

adb logcat -b crash -d -v threadtime > crash-log.txt

This dumps available crash-buffer entries, which can include other apps and older failures. Match timestamps and package/process details. It is not a complete ANR diagnosis. Inspect supported options with adb logcat --help; see the Logcat command-line reference.

4. Does the deep link actually reach the right screen?

Assume your manifest declares debugcli://product/42 as a supported route:

adb shell am start -W -a android.intent.action.VIEW -d 'debugcli://product/42' com.example.debugcli

The package restriction checks routing inside your app. Also test without that restriction to observe normal system resolution:

adb shell am start -W -a android.intent.action.VIEW -d 'debugcli://product/42'

Success means more than an activity opening: verify the destination, arguments, sign-in behavior, and Back navigation. A custom scheme doesn't prove HTTPS App Links verification. For HTTPS links, test the real domain and its verification separately. See Create deep links.

5. Does the feature handle a denied permission?

For an app that declares CAMERA and supports runtime permissions:

adb shell pm revoke com.example.debugcli android.permission.CAMERA
adb shell pm grant com.example.debugcli android.permission.CAMERA

Run these separately: revoke, exercise the denied path, then grant and exercise the granted path. Permission changes can affect the app process, so recheck its PID.

Shell grants don't test the permission dialog or every denial state. Also test the real request flow and the feature's fallback behavior. See Request runtime permissions.

6. Can you attach evidence to the issue?

adb exec-out screencap -p > debug-screen.png
adb shell screenrecord --time-limit 20 /sdcard/debug-demo.mp4
adb pull /sdcard/debug-demo.mp4 ./debug-demo.mp4

The recording command waits while recording. Pull the file after it finishes. Standard screenrecord doesn't record audio; protected content may be unavailable. See ADB screen capture and recording.

Turn the workflow into a useful bug report

Attach a short reproduction recipe with the variant, application ID, device/Android version, triggering command, expected result, and observed result. Add a timestamped log excerpt and a short recording when they explain the failure. Use test data and review logs and media before sharing them.

For your portfolio, include a DEBUGGING.md beside a sample app. Document one reproducible bug, the evidence that isolated it, and the fix. That shows the reasoning behind your tooling skills.

Which command saves you the most time when a bug refuses to reproduce from Android Studio?

Official references linked above. Commands are adaptable examples.

Prem Singh · Lead Android Engineer · Kotlin, Jetpack Compose & Android architecture

GitHub · LinkedIn

You already added debounce(300) and flatMapLatest. So why can the old request still finish?

The answer is operator placement. Debouncing reduces request frequency. It does not automatically cancel an in-flight search the instant the user edits the text.

The familiar pipeline has a timing window

Consider this simplified chain:

queries
    .debounce(300)
    .flatMapLatest { query -> searchFlow(query) }

After the user types car, the new value waits inside debounce. Until that value reaches flatMapLatest, the previous inner flow can continue. If the cat response arrives during that gap, it can still be emitted.

The Kotlin debounce reference describes suppression of rapidly followed values. The flatMapLatest reference describes cancellation when a new upstream value reaches that operator. Those are different moments.

This behavior can be acceptable when the UI deliberately keeps old results visible and labels them correctly. If you want a new query to cancel old work promptly, move the waiting period inside the switched flow.

Switch first, wait second

The following integration sketch accepts a Flow of query strings and a cancellable suspend search function. It separates waiting, loading, empty results, and failure so the UI can communicate each state clearly.

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.buffer
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.flow.flatMapLatest
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.map

data class SearchHit(val id: String, val title: String)

sealed interface SearchState {
    data object Idle : SearchState
    data class Waiting(val query: String) : SearchState
    data class Loading(val query: String) : SearchState
    data class Results(
        val query: String,
        val items: List<SearchHit>,
    ) : SearchState
    data class Failed(val query: String) : SearchState
}

@OptIn(ExperimentalCoroutinesApi::class)
fun searchStates(
    queries: Flow<String>,
    search: suspend (String) -> List<SearchHit>,
): Flow<SearchState> = queries
    .map { it.trim() }
    .distinctUntilChanged()
    .flatMapLatest { query ->
        flow<SearchState> {
            if (query.length < 2) {
                emit(SearchState.Idle)
            } else {
                emit(SearchState.Waiting(query))
                delay(300)
                emit(SearchState.Loading(query))
                try {
                    emit(SearchState.Results(query, search(query)))
                } catch (cancelled: CancellationException) {
                    throw cancelled
                } catch (_: Exception) {
                    emit(SearchState.Failed(query))
                }
            }
        }
    }
    .buffer(0)

This is a Flow-layer example, not a complete Compose app. Connect your repository and UI using dependencies compatible with your project. The experimental opt-in reflects the linked API reference; check the status for your coroutines version.

Now a new distinct, trimmed query reaches flatMapLatest before the delay. It cancels the previous inner flow, including its waiting period or cooperative in-flight request. The new flow then starts its own waiting period.

buffer(0) avoids an extra queued output buffer after the switching operator. It cannot retract a value the UI has already received, so keep the query attached to every result and render it honestly.

Keep text input responsive

Debounce the search operation, not the text field's displayed value. Typing and cursor movement should update immediately.

For state-based Compose text fields, TextFieldState owns editable text, selection, and composition. You can observe its text with snapshotFlow and feed that into the search pipeline. Preserve the text field state rather than replacing it with a fresh instance on every recomposition. The Android TextFieldState reference includes examples.

Choose the lifetime of the collector deliberately. For screen state on Android, lifecycle-aware collection is generally appropriate; a search operation should not accidentally gain a lifetime longer than its owner.

Three details worth getting right

A blank query must reach the switch. Filtering out short queries before flatMapLatest can leave an older search active when the user clears the field. This example emits Idle inside the switched flow instead.

Catch errors per request. The failure handler sits inside the inner flow. A failed request becomes a state while the outer query stream remains available for later input. A single catch after the whole pipeline can instead complete that collection after an error.

Cancellation is cooperative. A suspend function is not automatically well behaved. The repository must support cancellation and avoid blocking the calling thread. Cancelling a client request also doesn't guarantee the server stopped processing it. Never swallow CancellationException as an ordinary search error.

What about retrying the same query?

distinctUntilChanged intentionally suppresses equal adjacent queries. Assigning the same string again won't implement retry.

Model retry as a separate action. For example, include an attempt counter in a request model and increment it on retry, so the request stream sees a new value even when the query is unchanged. Decide whether explicit retries should bypass the typing delay.

Test the timing, not just the final list

Use a fake search implementation and virtual time to verify these scenarios:

A small demo showing the query, current state, and cancellation logs makes this a useful portfolio feature. It demonstrates an engineering decision that a polished screenshot alone cannot show.

The next time you review a search pipeline, ask: does cancellation happen when the user changes intent, or only after the debounce window?

Prem Singh · Lead Android Engineer · Kotlin, Jetpack Compose & Android architecture

GitHub · LinkedIn

For a search screen, live dashboard, or AI response view, this distinction matters. A UI collector and the producer behind it have separate lifetimes. Reviewing only one can leave unnecessary work running—or stop work that the product actually needs to finish.

Here's a small pattern worth understanding before adding more architecture to a Compose screen.

1. Collect screen state with the Android lifecycle

For an Android Compose route backed by a ViewModel, use lifecycle-aware collection:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.lifecycle.compose.collectAsStateWithLifecycle

@Composable
fun FeedRoute(viewModel: FeedViewModel) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()
    FeedScreen(state)
}

FeedScreen is your rendering composable; FeedViewModel is supplied by your app's normal ViewModel creation mechanism. Add androidx.lifecycle:lifecycle-runtime-compose using a version aligned with your project's Lifecycle dependencies.

By default, collection runs when the lifecycle is at least STARTED. It stops below that state and starts again when the lifecycle becomes active. This is different from ordinary collectAsState(), whose collection follows the composition rather than applying this lifecycle threshold. See the Android Compose state guide.

That fixes the consumer side. Now look upstream.

2. Give the upstream an explicit sharing policy

Here is an integration sketch for a repository that observes feed items. It assumes a cold Flow whose observation work is cancelled when its collector is cancelled. Adapt the model and repository to your app.

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.stateIn

data class FeedItem(val id: String, val title: String)

sealed interface FeedUiState {
    data object Loading : FeedUiState
    data class Content(val items: List<FeedItem>) : FeedUiState
    data object Error : FeedUiState
}

interface FeedRepository {
    fun observeItems(): Flow<List<FeedItem>>
}

class FeedViewModel(repository: FeedRepository) : ViewModel() {
    val uiState: StateFlow<FeedUiState> = repository.observeItems()
        .map<List<FeedItem>, FeedUiState> { items ->
            FeedUiState.Content(items)
        }
        .catch { cause ->
            if (cause is CancellationException) throw cause
            emit(FeedUiState.Error)
        }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(
                stopTimeoutMillis = 5_000,
            ),
            initialValue = FeedUiState.Loading,
        )
}

The explicit map result type allows both Content and Error to flow through the same pipeline. The cancellation guard makes the intended behavior clear: cancelling observation should not become a visible failure.

These are focused integration snippets, not a complete sample app. The repository, UI rendering, and dependency setup remain application-specific.

3. Read the timeline, not just the API name

With the policy above, the expected sequence is:

UI starts collecting       -> upstream observation starts
last subscriber disappears -> five-second grace period begins
subscriber returns early   -> existing observation continues
no subscriber after 5s     -> sharing cancels upstream collection
subscriber returns later   -> upstream collection starts again

The grace period can bridge short subscriber gaps such as configuration changes. Five seconds is a choice, not a universal performance rule.

The default replay expiration retains the last value: stopping the upstream doesn't automatically put uiState back into Loading. Returning users can see cached content while observation restarts. Read the Kotlin WhileSubscribed reference before changing cache behavior.

4. Know what this pattern does not stop

WhileSubscribed controls this sharing coroutine. It doesn't cancel every job in the ViewModel or shut down an independently running hot producer.

For example, this job has a different owner:

init {
    viewModelScope.launch {
        repository.refreshOnce()
    }
}

Here refreshOnce() represents an application-specific suspend function. Its job can continue after the UI stops collecting because it was launched separately in viewModelScope.

This can be intentional. An explicit user action and an observational feed don't always need the same lifetime. Decide whether an operation should stop when the screen becomes inactive, survive a navigation change, or require durable execution. Then choose its owner.

5. Handle failures and retry deliberately

The catch above turns a failure into an error state, but it does not continuously retry. Once that upstream attempt completes, a retry action needs an explicit strategy, such as a refresh trigger that starts a new observation, or a bounded retryWhen policy before catch for suitable transient failures.

Don't rely on backgrounding and reopening the app as the user's retry mechanism. Also consider retaining existing content alongside a refresh error when that serves the screen better.

A useful code review exercise

For the next Flow-backed screen you review, trace four things:

1. Which lifecycle controls the UI collector?

2. Which scope owns the producer?

3. Does cancellation actually reach the underlying work?

4. What happens after failure, and who triggers another attempt?

For a portfolio demo, instrument a fake cold Flow with start and cancellation logs, then record navigating away and returning before and after the timeout. Show the logs beside the screen recording. That demonstrates the behavior far more clearly than a screenshot of an API call.

The key design decision is ownership: the screen's visibility, the observer's lifetime, and the operation's lifetime should each be intentional.

What do you usually find in reviews: missing lifecycle-aware collection, or upstream work with an unexpected lifetime?

Prem Singh · Lead Android Engineer · Kotlin, Jetpack Compose & Android architecture

GitHub · LinkedIn