penwyp/claudepreference/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.

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.