arisguimera/mobiai-core/mobiai-mobile-debugging

Systematic Mobile Debugging

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

<HARD-GATE> You MUST NOT propose any fix, write any code, edit any production file, refactor any surrounding code, or invoke mobiai-mobile-tdd until you have (a) gathered evidence, (b) separated what is known from what is assumed, (c) formed and verified a hypothesis, and (d) stated the root cause.

Whether you also need explicit user confirmation at steps (b) and (d) depends on the scope classification inherited from the caller (or declared at Pre-flight below). Fast path: no confirmation gate, proceed autonomously. Gated path: explicit confirmation required at both steps. </HARD-GATE>

Anti-Pattern: "It's Obviously X"

The most common failure mode is pattern-matching the symptom to a familiar-looking cause and proposing a fix before the evidence supports it — especially when a sub-agent or exploration returns a confident diagnosis that was never cross-checked against the code. Threading, null, lifecycle, cache, "the backend changed" — all tempting guesses. Every bug goes through the phased flow.

The scope classification only changes whether you wait for user confirmation, not whether you do the analysis. Fast path still gathers evidence, splits known vs. assumed, forms and verifies a hypothesis, and states the root cause — it just returns that result to the caller instead of pausing for approval.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Pre-flight: Scope Classification

This skill inherits the scope from its caller (typically mobiai-fix-issue). If invoked standalone, classify at the start:

Fast path — work autonomously through all phases; return the verified root cause to the caller at Phase 6:

• Clear symptom with obvious evidence (stack trace points at a specific line, log message is explicit)
• Single root cause category (not contradictory evidence)
• No architectural question, no cross-module mystery

Gated path — stop and wait for user confirmation at Phase 2 and Phase 5:

• Contradictory evidence or multiple plausible causes
• Cross-module / cross-platform investigation required
• Root cause involves architectural choices (e.g., "should this be on the main thread?")
• Previous fix attempts failed

In doubt → gated path.

Checklist

You MUST create a task for each of these items and complete them in order. Do not skip phases. Do not merge phases.

1. Gather evidence — logs, stack traces, reproduction steps, affected platforms, recent changes
2. State known vs. assumed — label each fact as observed or inferred (gated path: present to the user and wait for confirmation; fast path: record the split internally and proceed)
3. Form a hypothesis — a single, specific, testable theory about the root cause
4. Verify the hypothesis — against code and evidence, not against intuition
5. Present the root cause (gated path: wait for user confirmation before Phase 6; fast path: state the root cause and proceed to Phase 6)
6. Hand off to implementation — return control to mobiai-fix-issue if the broader pipeline is active, or invoke mobiai-mobile-tdd

When to Use

Use for ANY mobile technical issue:

• Test failures
• Bugs in production
• Unexpected behavior
• Performance problems
• Build failures
• Crashes

Use this ESPECIALLY when:

• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• A previous fix didn't work
• A sub-agent or exploration returned a confident diagnosis

Don't skip when:

• Issue seems simple (simple bugs have root causes too)
• You're in a hurry (rushing guarantees rework)

Pre-flight: check the Brain for overdue debt

Standalone invocations only — skip this section when called from `mobiai-fix-issue`, which already runs its own pre-flight review and would otherwise double-prompt.

If <repo>/.mobiai/brain/config.json exists, do a quick review pass before forming hypotheses. The issue you're investigating might be related to a known workaround already logged as temporary debt; checking up front prevents re-deriving an answer that's already in the brain.

Preferred — MCP tool (when mobiai-brain MCP server is registered):

Invoke mobile_review with default args. From the returned overdue list, focus on entries whose platform matches the project's platform and whose area overlaps with the symptoms (component, module, feature where the bug shows up). Run mobile_scan first if you don't already know the project's platform.

Fallback — CLI:

mobiai brain review --no-fail

If 1+ overdue entries match, mention them to the user before Phase 1:

"Heads up — there are N overdue temporary workaround(s) in <platform>/<area> that may relate to what you're seeing: <title>. I'll proceed with the investigation; let me know if you want to look at those first."

Then continue with Phase 1. Don't pause unless asked. Skip silently when:

• The brain isn't initialized.
• No overdue entries match the area / platform of the issue.

Pre-flight: check the Graph for code structure

Standalone invocations only — skip this section when called from `mobiai-fix-issue`, which already runs its own Graph pre-flight at Phase 1.

The Graph indexes Kotlin/Swift symbols and can rank files by relevance to a symptom — useful for Phase 1 (Gather Evidence) and Phase 3 (Form a Hypothesis). Brain says "what's known about this area"; Graph says "where the affected code lives today".

If `<repo>/.mobiai/graph/index.json` exists:

# Freshness — if "hace Xd" with X ≥ 1, suggest refresh (don't auto-run):
mobiai graph status
 
# Locate relevant files from the symptom (top results = where to look first):
mobiai graph context "<one-line symptom or bug title>"
 
# If a symbol appears in the stack trace, find its callers:
mobiai graph callers <SymbolFromStackTrace>

If the index is ≥1 day old, mention it to the user before continuing:

"El índice del Graph es de hace Xd. Si querés resultados frescos, corré mobiai graph init."

Don't run init autonomously — let the user decide.

If `.mobiai/graph/index.json` does not exist and the project has .kt or .swift files:

"No veo el índice del Graph. Generalo con mobiai graph init y vuelvo a buscar — sin él tengo que grep a ciegas y leer más archivos de los necesarios."

Don't run init autonomously.

Skip silently when:

• The project has no Kotlin/Swift files (Flutter-only or RN-only without native code).
• The bug is purely in resources, config, or build files (Graph won't help).

Phase 1: Gather Evidence

Before forming any opinion, collect the raw material.

1. Read error messages carefully

• Don't skip past errors or warnings
• Read stack traces completely
• Note line numbers, file paths, error codes

1. Confirm reproducibility

• Can you trigger it reliably?
• What are the exact steps?
• If not reproducible → gather more data, don't guess

1. Check recent changes & find the breaking commit

• What changed that could cause this?
• git log --oneline -20 -- <affected-file> — commits that touched the affected file
• git blame -L <line>,<line> <file> — which commit last changed the specific failing line
• git log --all --grep="<keyword>" — past related fixes that might show the introduction of a conflicting pattern
• If this is a regression: identify the commit that introduced the bug. Record its SHA and subject. Use git bisect when the history is dense or the search space is large. The breaking commit goes into the PR description (it helps the reviewer assess scope and decide backport priority).
• If the bug has always existed (not a regression): state that explicitly. "Always-existed, not a regression" is valid and important information for the reviewer — don't leave it ambiguous.
• New dependencies, config changes, Gradle/SPM/pubspec bumps can themselves be the breaking commit.

1. Collect concrete evidence

Add diagnostic instrumentation at component boundaries:

1. Identify affected platforms precisely

• Does it happen on Android only? iOS only? Both? Specific OS versions? Specific devices?
• Precise platform scope often points directly at the root cause category.

Phase 2: State Known vs. Assumed

Separate what you actually observed from what you are inferring. List in two columns:

• Known (direct evidence): log lines seen, stack traces captured, reproduction confirmed, git diff contents
• Assumed (not yet verified): "probably caused by X", "likely a threading issue", "the backend probably returned null"

Every item in "Assumed" is a candidate to either verify (moving it to Known) or to drop.

• Fast path: record the split internally, proceed directly to Phase 3.
• Gated path: present the split to the user and wait for confirmation before Phase 3. If the user corrects an assumption, update the list.

Phase 3: Form a Hypothesis

One hypothesis at a time, stated specifically. Not "it's a race condition" — rather "the ViewModel's observeUser() coroutine is cancelled by the Activity being recreated on rotation, so the subsequent emission is dropped".

Check common mobile bug categories to frame the hypothesis:

Lifecycle bugs:

• Android: Activity/Fragment recreated after rotation? ViewModel cleared after process death? onSaveInstanceState missing?
• iOS: View controller deallocated? viewWillAppear vs viewDidLoad timing? SceneDelegate lifecycle?
• Flutter: Widget rebuilt unexpectedly? State lost on navigation? dispose() not called?
• React Native: Component unmounted during async operation? Navigation state stale?

Threading bugs:

• Android: Accessing UI from background thread? Coroutine on wrong dispatcher?
• iOS: UI update not on main thread? Data race in concurrent queue? @MainActor missing?
• Flutter: Isolate communication issue? setState after dispose?
• React Native: Native module callback on wrong thread?

Memory bugs:

• Android: Context leak in singleton? Inner class holding Activity reference?
• iOS: Retain cycle in closure? Missing [weak self]?
• Flutter: Stream subscription not cancelled? Controller not disposed?
• React Native: Event listener not removed in cleanup?

Data bugs:

• SQL/Room/CoreData: Wrong query? Migration missing? Schema mismatch?
• SharedPreferences/UserDefaults: Wrong key? Type mismatch?
• API: Response format changed? Null field not handled?

KMP-specific:

• Divergence between actual implementations across platforms
• Freezing/threading models in legacy Kotlin/Native
• Serialization differences between JVM and Native