Frontend/UI Bug Reproduction and Verification Gate

This process is mandatory for reported Seed UI defects. It prevents source-first debugging and false fixes based only on unit tests or code inspection.

State machine

REPORTED → BASELINE_LOCKED → REPRODUCED → FIX_ALLOWED + PR_ALLOWED → VERIFIED

BLOCKED is valid only with a concrete artifact showing why the target cannot run or why a surface is inapplicable. A failed tool installation is not reproduction. No draft or ready PR is allowed before REPRODUCED; blocked work stays local.

Intake

Read the complete GitHub issue, attachments, comments, platform, and version.

Translate it into one observable assertion, preserving the reporter's sequence.

Select a clean baseline SHA where the report should still be reachable. Never start from a prior fix branch.

Default matrix: web-desktop, web-mobile, and desktop-electron. Mark a row inapplicable only from explicit product/platform evidence.

Baseline reproduction (before source edits or any PR)

No product-source patch may be started before this gate passes. Investigation, harness work, and neutral diagnostics are allowed only when they do not encode a speculative fix.

The reproducer must exercise the reporter-level sequence and fail on the reported observable assertion. Evidence of only a suspected mechanism—such as a scroll call, transient DOM/CSS state, or mocked callback—does not qualify when the reported visible failure is absent. Instrumentation may observe behavior but must not manufacture the state being claimed as the defect.

Web

Boot a local daemon and web app with isolated data and fixed ports.

Run Sentinel QA with an issue-specific goal when its model/provider is available.

Always capture a deterministic Playwright regression for the exact assertion; Sentinel exploration alone is not the acceptance gate.

Save a before-video by default, plus trace, screenshot, page URL, viewport, browser version, console errors, failed requests, and server logs. A screenshot is sufficient only when the entire defect is static and that choice is justified in the manifest.

Desktop

Package the current baseline and launch it with Playwright _electron using a unique VITE_DESKTOP_APPDATA.

Execute the same user-level assertion in the renderer.

Save before-video of the packaged app, Playwright trace, screenshot, Electron console/page errors, daemon logs, package SHA, and app-data path.

Sentinel’s agentic browser currently launches Chromium rather than Electron (pi-ext/qa-browser/index.ts). For desktop, use Sentinel’s deterministic acceptance engine to own an external lifecycle that invokes Playwright _electron; do not describe that run as agentic exploration.

Fix and PR gate

Product source edits and pull-request creation (including drafts) are allowed only after:

the acceptance test fails for the expected behavioral reason on each applicable surface;

false failures (boot, auth, fixture, missing dependency) are excluded; and

the artifact manifest says REPRODUCED.

Record the exact baseline evidence before opening the PR, and link it from the PR description. If any condition is unmet, keep investigation local and request the missing reproduction conditions on the issue; a draft PR is not a substitute for this gate.

Keep the acceptance test unchanged while implementing the fix. Add narrower unit/integration tests only after the user-level failure is secured.

Verification

Run the unchanged acceptance test on the fix SHA in both environments and capture after-video of the same user sequence. The bug is VERIFIED only when all applicable rows pass, public before/after proof is linked in the PR, and artifacts identify the exact fix SHA. Also run focused unit/integration coverage and relevant neighboring interactions. A code review, DOM inspection, mocked component test, or green CI run alone is not verification.

Failed reproduction path

If the exact observable failure does not occur, stop before product edits. Publish or comment with the precise baseline SHA, app surface, setup, steps attempted, and what happened instead. If a required condition is genuinely unknown, ask for it; otherwise mark the lane deferred and revisit only when new evidence arrives. Never convert a suspected implementation mechanism into a substitute bug report.

Sentinel issue-driven use

Sentinel target command: bin/sentinel run <target> qa. Its configured qa.app.goal must quote the issue's user steps and expected/actual behavior. Use local targets by default. Never set allow_live_data:true merely to make a run convenient. Sentinel may explore and discover adjacent problems but must not file issues automatically during reproduction (qa.issues omitted).

Because Sentinel lacks GitHub-issue intake today, Ion’s issue lane owns issue selection, deterministic Playwright specs, before/after pairing, and evidence publication. Sentinel now orchestrates both web acceptance and external Electron acceptance; its model-driven exploration supplements rather than replaces exact assertions.

Artifact contract

Each project keeps artifacts/ui-bug-gate/<issue>/manifest.json plus immutable logs/media. Each applicable surface must define expectedFailurePattern; baseline failures count only when their logs match that bug-specific pattern. Use bin/ui-bug-gate.py to execute and evaluate the four before/after commands. The manifest must include baseline/fix SHAs and per-surface exit results.

Scope

The no-reproduction/no-product-edits/no-PR boundary applies to every reported defect, not only UI bugs. Non-GUI work uses the reporter’s externally observable assertion and appropriate logs or traces. The platform matrix and video requirements above apply to GUI work. Before code, record expected/actual behavior, assumptions and an attempt to falsify the suspected mechanism.