Tune the crawler: evidence → failing test → fix → re-crawl

Never fix exploration by guessing. Each fix follows this loop:

1. Evidence. Get the run's health report and find the steps where it went wrong.

   uv run appscreenmap-engine report runs/<project>/<run-id>
   grep -n '"effect": "same_screen"' runs/<project>/<run-id>/trace.jsonl | head     # wasted taps

   The hierarchy of every screen is in runs/<project>/<run-id>/screens/<sid>.xml. To capture the live screen:

   uv run python -c "
   from appscreenmap.drivers.android import AdbDriver; from appscreenmap.core.analyzer import analyze
   d=AdbDriver(); s=d.snapshot(); w,h=d.screen_size(); o=analyze(s.xml,None,s.activity,w,h)
   print(o.title, o.patterns, o.signature)
   for e in o.elements: print(e.kind, e.action, repr(e.label), e.group, e.key)"

   To print the tree with groups, walk parse_hierarchy() + _mark_repeats(); see how packages/testkit/src/appscreenmap/testkit/helpers.py models Compose output.
2. Failing test. Reproduce the structure in packages/core/tests/ (screen identity) or packages/crawler/tests/ (exploration) with the node() / hierarchy() helpers. Use synthetic data only; never commit real app dumps, since they contain user content.
3. Fix in the right layer (map below). Keep the change minimal and explain why in a comment only where it's non-obvious.
4. Verify. Run uv run pytest -q && uv run ruff check && uv run ruff format, then re-crawl the Playground with --clear-data and compare report numbers before and after (steps/screen, no-ops, near-duplicates, nav failures). Then add the re-run to the Playground canvas (merge --into <canvas> <run> --move, see the crawl-app skill) instead of leaving a new run behind.

iOS crawl? Start with the ios-simulator skill: its table of symptoms (missing tab bar, in-app browser, blank trees) separates app accessibility gaps from crawler bugs before you change any code.

Symptom → where to look

Lessons already learned (don't regress)

• Compose flattens LazyColumn rows into leaf siblings, so leaves are only list rows inside real ListView/RecyclerView/GridView.
• Digits are normalized (10:15 → ##:##) for identity. Colliding element keys get #2, #3 instead of being dropped.
• Nested controls inside list rows (a card's "MORE") form their own group.
• ListView rows are often not clickable; they're treated as implicitly clickable.
• BACK can close search screens, so the keyboard is hidden with ESC.
• BACK at the app's root exits the app, so the app is pinned via am task lock. A force-stop unpins, so restart() re-pins.
• A screen first seen outside a recorded action has origin: unknown and gets a path the first time a known screen leads there. Only restart() may mark origin: launch (an empty path means "launch lands here"). The viewer builds its tree from reach_path, so never leave a pathless screen looking like a root.
• An action that only changes scrolled content (a tap that scrolls the list, a WebView exposing its text) must not create a new screen. identify(obs, hint=src) keeps the source screen when the fixed part (fixed_tokens: outside scrollers/WebViews: title, toolbar, nav) is unchanged.
• Android 10+ often shows no crash dialog: the app just disappears and another app comes to the front. When the app leaves the foreground, check logcat -b crash for Process: <pkg>, before calling it "left the app".
• First-run screens (sign-in, onboarding) disappear once the app saves state. With --clear-data the crawler may pm clear once to get back (data_reset event, max 5 per crawl).
• Pinning shows an "App pinned" toast; restart() waits it out so screenshots (and visual diffs) stay clean.
• Stdout must be line-buffered, or background logs stay empty.

Add new lessons here when a fix teaches something general.