browser-flow-fallbacks

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.