Scenario

scenario — Edge Case & Scenario Explorer

Systematic pre-implementation scenario analysis. For a given feature or change, produces a severity-ranked table of test scenarios across 13 dimensions tuned to gflow-cli's known failure surfaces. Feed the output into PLAN.md tasks and tests/features/ BDD scenarios before entering EXECUTE mode.

When to invoke

Use before implementing any of:

• A new generation path (T2V, I2V, R2V, batch manifest runner)
• Transport changes (any new HTTP call against aisandbox-pa.googleapis.com)
• Auth or session changes (new strategy, cookie extraction, SAPISIDHASH wiring)
• Selector cascade changes (ONBOARDING_SELECTORS, NEW_PROJECT_SELECTORS, FRAME_SLOTS_STRUCT, IMAGE_MODEL_OPTION_SELECTORS)
• Data layer changes (schema migration, new OperationRecorder callsite, redaction change)
• New CLI subcommand, flag, or exit code

Skip for: pure doc changes, CHANGELOG/version bumps, scripts/ tooling with no production callpath.

Invocation

/gflow:scenario <feature or change description>

<feature or change description> is a brief summary of what you're about to implement. Examples:

• "SAPISIDHASH auth header wired into _post_json for aisandbox-pa routes"
• "gflow video batch manifest ledger (skip already-completed rows)"
• "Image model picker converted from English has-text to structural anchor"
• "CDP-attach transport as opt-in alongside ui_automation"

The 13 dimensions

For each dimension, enumerate scenarios that are non-obvious — do not list things that a basic happy-path test already covers. Focus on things that break in production but pass in unit tests.

D1 — Auth & session lifecycle

The SAPISID cookie expires. The user re-runs gflow auth login mid-batch. A profile is created but the Flow session was never verified. The session is valid for labs.google tRPC but not for aisandbox-pa. Two profiles are in use simultaneously (Chromium profile-lock).

D2 — WAF / reCAPTCHA scoring

A profile's WAF heat score is elevated from prior automation runs. reCAPTCHA Enterprise detects navigator.webdriver=true despite the --disable-blink-features stealth flag. The grecaptcha.execute() call times out or returns a challenge that requires human interaction. The same token is submitted twice (single-use token reuse). A batch run fires multiple rapid token mints within one session.

D3 — Selector cascade drift & Locale Invariance (Flow UI updates)

Google Flow ships a UI update that renames or restructures a selector anchor. FRAME_SLOTS_STRUCT matches zero elements (the PR #70 regression). The structural-first tier matches but selects the wrong element (e.g., two elements matching div[type='button'][aria-haspopup='dialog'] after Flow adds a new dialog button). A non-English locale is used (e.g. GFLOW_CLI_LOCALE=pt-BR or a Brazilian Google account) and single-language English text selectors fail because they lack Tier 1 structural anchors (a[href*='changelog'], button:has(i:text('close'))) or Tier 2 multi-locale text cascades. A new locale is used whose CMP dialog is not in _ONBOARDING_TEXT_SELECTORS. The --lang=en-US Chromium arg is removed before IMAGE_MODEL_OPTION_SELECTORS is converted to structural anchors.

D4 — Batch manifest & resume

A 50-row TSV manifest dies at row 23 (auth expiry). On resume, rows 1–22 are re-submitted and double-billed. A row has an empty start_image field (T2V) while the column parser expected a path. The output path already exists on disk from a prior run (overwrite vs skip decision). Two gflow video batch invocations against the same profile run concurrently (Chromium profile-lock).

D5 — Concurrency & Page pool

GFLOW_CLI_CONCURRENCY=16 fans out 16 simultaneous page.evaluate() reCAPTCHA token mints — do they share site key state safely? A Page is returned to the pool while still in a modal dialog (state contamination for the next checkout). A QueueFull double-checkin race where two coroutines both attempt to return the same Page object. asyncio.gather propagates one failure but leaves the other coroutines in a half-completed state with no cleanup path.

D6 — Data layer (SQLite / DataStore)

DataStore migration runs on a schema that's one version ahead (newer-schema detection should raise DataStoreError exit 16, not silently corrupt). An OperationRecorder.on_started callback raises inside a generation loop — does the batch continue or crash? GFLOW_CLI_HISTORY_PROMPTS=redacted is set — does the new callsite respect the redaction gate? A Windows path with a drive letter is stored in the DB and retrieved on Linux (or vice versa). The DB is on a network filesystem and the write locks time out.

D7 — Error propagation & exit codes

A new exception class is added but not registered in EXIT_CODE_MAP. A FlowApiError subclass is raised inside a retry loop — does reraise=True propagate the right typed exception or does tenacity eat it? WireFormatError discovery payload logs the route body prefix — does it redact reCAPTCHA tokens and auth headers? An unhandled exception escapes run_with_handlers — is it SHA-256-hashed before logging (never raw message)?

D8 — Cross-platform paths

A Windows user has a Unicode character in their %LOCALAPPDATA% path. The output directory path contains spaces. platformdirs returns a different base path on macOS vs Linux vs Windows — does the feature hardcode any of these? PYTHONUTF8=1 is not set — are there cp1252 encoding traps on Windows for prompt text or file names?

D9 — Transport edge cases

The HTTP response body is valid JSON but has an unexpected top-level key (should emit WireFormatError with discovery payload, not crash). A video generation response omits operations[0].operation.name (the omni-flash NULL flow_operation_id issue). A status-poll response arrives before the listener is attached (_attach_status_response_listener race). A video download URL has a googleapis.com host not in the SSRF allowlist.