debug-async-ui

Debug Async UI

Use this skill before changing visuals for async interaction bugs. Prove which layer owns the failure: event, state, data, lifecycle, or render.

Workflow

1. Reproduce the original symptom first. Capture the user action, the immediate UI state, and the final UI state after async work completes.
2. Add a slow-request regression test before the fix. Simulate 200-500 ms API, database, provider, or store delay. Assert:
   • the immediate intermediate state is visible after the action;
   • the final returned state/content is visible after resolution;
   • the target component was not incorrectly unmounted;
   • global loading did not replace a local interaction surface. For startup or splash gates, also add a regression where the readiness future never completes. The app must leave the splash/loading route through a bounded timeout or an explicit fallback instead of waiting forever.
3. Trace the layers in order:
   • Event: click, hover, keyboard, wheel, or submit handler fires exactly once.
   • State: selectedId, detailId, expandedId, edit state, pending state, and result state are written where expected.
   • Data: API/database/provider/store refreshes do not overwrite the target state.
   • Lifecycle: route changes, keys, conditional rendering, AnimatedSwitcher-like components, and loading branches do not unmount the owner of interaction state.
   • Render: UI actually binds to the correct state after the previous layers are proven.
4. Fix the root cause, not the symptom. Move durable interaction state to a stable parent/controller/store when a child can be replaced by loading, routing, or conditional rendering. Use local loading for detail open, local refresh, save title/color/sort, and similar narrow operations. Reserve global loading for initial load or broad data-source switches.
5. Check the trigger boundary. If the user expects generation for the current entity, trigger from stable entity selection/page context, not only from narrow record-kind flags such as "external candidate". Manual buttons should remain as retry controls, not the only path to generation.
6. If the operation affects the currently viewed entity, surface status and returned content on every stable context where the user may remain while waiting, including the active tab, default overview, and relevant side panel. Do not leave the only evidence in an off-screen tab, transient child panel, hidden side panel, or default page the user is not currently viewing.
7. For aggregate responses, distinguish "request finished" from "required sub-result returned". If a key source, model, provider, or structured field is missing from the returned payload, show an explicit missing/failed diagnostic on the same stable contexts; do not let a broad "ready" status imply the missing sub-result succeeded.
8. For AI/model synthesis that supplements several factual modules, centralize extraction from the real response in a stable parent and render module-specific supplement panels. Each panel must label loading, failure, missing sub-result, or completion; completed AI content must be marked as AI-generated and must not be merged into authoritative facts unless the normal source-gating path approves it.
9. For slow search/detail generation, never leave the previous selected entity visible while the new query is pending. After a short threshold, render a query-scoped pending placeholder in the stable parent, label it as generating, and suppress duplicate detail verification for that placeholder. When the aggregate search resolves, replace the placeholder with the real returned candidate or an explicit empty/error state.
10. For launch Aha screens, onboarding tours, permission primers, marketing modals, or other delayed overlays, gate later overlays on the dismissal/completion state of the current primary surface. A timer-driven tour must not appear on top of an undismissed launch panel, auth gate, consent gate, or blocking first-run task. Add a delayed regression that waits longer than the overlay timer while the primary surface remains open.
11. For mobile floating action clusters, measure the actual bounding rectangles of every simultaneously visible trigger. Assert all triggers are inside the viewport and pairwise non-overlapping. Treat the cluster as one layout system rather than moving one button at a time. When an opened sheet/panel should cover those triggers, assert the panel is in the viewport and has an overlay layer above persistent top/bottom controls.
12. For mobile overlays containing text inputs, check whether opening the overlay auto-focuses an input. On Android and other touch-first contexts, auto-focus can cause the first hardware/back gesture to clear input focus or keyboard state instead of closing the overlay. Prefer no mobile auto-focus unless text entry is the sole immediate task, and add a regression that the expected back/overlay history path closes on the first action.
13. For external OAuth/device-code flows, separate "browser-side approval" from "app-side token/profile completion." The app must keep the device code and waiting state visible while polling, and transient DNS/connection/timeouts from token or profile endpoints should update a retrying status rather than switch to terminal failure. Add a regression where the first token poll or profile request fails with a network error and the next retry succeeds; assert no error UI appears and the signed-in state eventually renders.
14. For auth-bound forms with quick-fill presets, templates, or shortcuts, assert that applying the preset does not clear authenticated identity, creator, token, tenant, workspace, or attribution fields. Re-read the stable auth/session store at the submit boundary as a fallback, because the visible form field may have been cleared by a preset, locale switch, or overlay remount.
15. If one part of an authenticated flow uses native/mobile-safe retry semantics, adjacent authenticated actions such as submit, publish, save, or create-record should use the same retry class for DNS, connection, timeout, HTTP 0, and 5xx/429 states. Add a regression where the first submit/publish request fails transiently and the next retry succeeds.
16. Verify with the slow regression plus relevant static checks, build, and browser checks that switch every affected tab/module.
17. For file-backed or local-database UI state, inspect write ordering as well as restore ordering. Two unawaited saves can race even when each save is individually correct: an older snapshot may finish last and overwrite a newer terminal/error/result state. Serialize complete snapshot writes (or use an atomic transaction), establish restored terminal guards before publishing restored content, and gate entitlement/lifecycle auto-retries until hydration completes. Run the restart regression repeatedly and add a 200-500 ms delayed hydration case where entitlement becomes active before the persisted state arrives.