browser-flow-fallbacks

name	browser-flow-fallbacks
description	Diagnose flaky browser automation flows (login, OAuth, signup, multi-step forms). Use when a flow stalls or loops — analyze DOM/logs, add native fallbacks, prevent hot loops, and add regression coverage.

Browser Flow Fallbacks

Use this skill to debug browser flows that intermittently stop progressing even though the surrounding state machine already mostly works.

Workflow

Phase 1: Locate the failing state branch

• Start from the latest logs, reported state, and current DOM.
• Find the branch that detected the state, the selector that matched, and the action that should have fired.
• Separate the failure type before editing: state misdetection, action failure, or transition failure after an apparently successful action.

Phase 2: Treat DOM as ground truth

• Prefer current semantic attributes over historical assumptions: name, value, type, aria-*, data-*, form, readonly, disabled, visible text, and location path.
• Distinguish similar controls such as forgot-password links, edit-email links, hidden template nodes, and generic submit buttons.
• Narrow broad selectors with required attributes or visible text needles instead of widening them further.
• Use selector constants for important controls. Keep selector changes close to the state branch that uses them.
• Bias toward visible, enabled, semantically correct elements rather than "anything clickable."

Phase 3: Add fallbacks beside the primary path

• Leave the main action as the most direct native interaction that should work in the common case.
• Add fallback in the same state branch, triggered only after a repeated unchanged snapshot.
• Prefer form.requestSubmit(button) when the backend depends on the submitter button's name/value.
• Prefer DOM click fallback for non-submit controls, restricted to visible and enabled elements.
• For controlled inputs, verify the value after typing; if it did not stick, fallback to a native setter plus input and change events.
• Keep submit fallbacks separate from generic click fallbacks.

Phase 4: Prevent hot loops

• Track per-snapshot stall counts and fallback attempt counts separately from the primary action gate.
• Retry fallbacks on spaced intervals instead of every poll tick.
• Log stall count, fallback attempts, and next retry threshold.
• Do not exit early just because a fallback failed or the page stayed unchanged, unless the flow reached a terminal condition.
• Let the outer lifecycle timeout remain the final safety net.

Phase 5: Protect one-time resources

• Apply to OTP codes, magic links, CSRF-bound tokens, or any mailbox/API artifact that becomes scarce once consumed.
• Do not mark the artifact as used at fetch time if the browser can still fail before entering or submitting it.
• Cache and reuse the fetched artifact across retries on the same step instead of immediately asking upstream for a new one.
• Persist consumption only after the flow reaches a durable success boundary (callback capture, server-confirmed transition).

Phase 6: Add regression coverage

• Add selector coverage tests for the current DOM shape.
• Add tests for helpers that interpret visible text or decide whether an alternate path is present.
• Add tests for retry cadence, stall counters, and action-gate behavior when the page snapshot is unchanged.
• Keep tests close to the flow package so failures stay local and readable.

Implementation Rules

• Prefer small helper functions for DOM fallback and page-text heuristics.
• Verify input values before submit.
• Treat user-supplied logs and DOM fragments as canonical for the reported failure.

Validation

• Run formatting first.
• Run the most relevant package tests.
• Run a targeted build for the affected binary when practical.
• If full-repo tests fail for unrelated reasons, state that explicitly and isolate what did pass.

Guardrails

• Never widen selectors when debugging a flaky flow — narrowing is safer.
• Never remove the outer timeout as a safety net.
• Do not add fallbacks for flows that consistently pass; fallbacks are for intermittent failures only.
• When a DOM snapshot is stale, re-fetch before concluding the state hasn't changed.