[roadmap] /ba:prove — capture screenshot evidence of a feature for the MR

[azevedo]

Idea

A last-mile command that captures objective screenshot evidence that a feature works and stages it for attachment to the MR/PR. Lately this has been done by hand with chrome-devtools MCP (or agent-browser): drive the app, often mock network requests to reach different scenarios (empty / error / loading / success), snap screenshots, attach to the MR.

This lives at the same last-mile moment as /ba:polish (server up, browser open, last step before shipping) and shares the ui-driver / browser seam — but it is a different lane and should not be folded into polish.

Why it is not polish (and not review)

Same moment + same tooling, but different on every axis the polish brainstorm locked down:

	polish	/ba:prove (this)	(verification — separately deferred)
Signal	subjective (feel)	objective (it works)	objective (it works)
Audience	you, now	the reviewer, later	the agent, as a gate
Output	ephemeral, no artifacts	durable artifacts (PNGs on the MR)	pass/fail
Drives state	observes current state	constructs states (mock network per scenario)	constructs states

Folding it into polish would break polish's locked identity ("purely conversational, no persisted artifacts, subjective feel"). It also doesn't belong in /ba:review (server-less and already slow).

Proposed shape

• Own command, /ba:prove (its own lane: distinct audience + a non-trivial mocking core), orchestrated by /ba:propose since the artifact is MR-facing — e.g. /ba:propose --capture calls it, or it runs standalone.
• Shares the ui-driver seam with polish; does not reach into polish's conversational loop.
• Cheap → expensive split:
  • v1 (mock-free): capture the happy path — navigate (or hand it routes), snap, stage images for the MR body. Immediately useful.
  • v2 (scenario-driven): define states, mock network per state, drive + snap each. The real value, the real cost. Likely overlaps with the repo's existing mocking (MSW-style / fixtures).

Prior art — Every's compound-engineering plugin

• ce-demo-reel — closest match. Core principle: "Evidence means USING THE PRODUCT, not running tests." Captures tiers (browser GIF / terminal recording / screenshot reel / static PNGs / no-evidence), scans for secrets before upload, uploads to a public host, returns {tier, description, url, path}, and the caller integrates it into the PR description under a "Demo"/"Screenshots" label. Strong template for the artifact + propose hand-off.
• ce-test-browser — diff→route mapping, test each page, pass/fail table. This is the verification lane (objective gate for the agent), not this issue — useful reference for the deferred verification idea instead.

Key divergence: neither Every skill does network mocking / scenario states — they capture whatever happy-path state the app is in. The scenario-mocking layer is the net-new, expensive part of this idea and the thing to scope carefully.

Borrow from ce-demo-reel

• Tiered capture with a graceful "no evidence needed" tier (text/config-only changes).
• Secret scanning before any upload (patterns like sk-, ghp_, Bearer, ?token=); set credentials outside the captured region.
• Standardized return that propose splices into the MR body.

Meta-insight (ui-driver seam)

This is the second concrete consumer of the ui-driver seam (after polish; verification would be a third). That's the justification we said was missing when we deferred the seam-as-extension-point — it upgrades "ui-driver seam" from polish-private convenience to deliberate shared last-mile browser infra. Doesn't change v0 polish scope; it's a reason to keep the seam clean.

Open questions

• Standalone /ba:prove vs. /ba:propose --capture vs. both?
• Where do scenario definitions live — inline args, a small config, or reuse existing test fixtures/mocks?
• chrome-devtools MCP vs. agent-browser as the driver (request interception for mocking is the deciding capability).
• Host/attach screenshots how — upload to a public host (ce-demo-reel style) vs. commit into the MR vs. inline?

Status

Deliberately a roadmap item, not scheduled. Gated on the ui-driver seam existing. Distinct from /ba:polish (feel) and the separately-deferred verification/gate idea.

https://claude.ai/code/session_014AfNMUnKn3oAsZhvNk5Vxa

[azevedo]

Two architecture notes that change this issue's dependency graph

Coming back to this after looking at how scenario-mocking actually plays out in practice — two refinements to the v1/v2 split and the open questions.

1. v2's cost is per-repo discovery, not the mocking itself → gate it on a per-repo mechanics doc

The issue treats v2 (network mocking per scenario) as the expensive, scope-carefully part. Worth splitting that cost in two:

• The mocking code is small — runtime request interception (wrapping the fetch/XHR layer via an injected init script) is on the order of tens of lines once you know the app's quirks.
• The expensive part is discovering and caching those quirks per repo: does the data layer go through fetch or XHR (an interceptor on the wrong one silently no-ops), does it transform keys between the wire and the app (mock the wrong casing → patch fires, UI unchanged, false pass), is the mock dropped on reload, how do feature flags toggle, what seed users/state exist.

None of that is portable. So the realistic architecture is a thin generic harness + a per-repo "mechanics" plug-in:

• Generic / ship-now (v1): navigate → snap → secret-scan → stage → hand to propose. Repo-agnostic.
• Per-repo / deep (v2): how to reach a scenario state in THIS app. Every repo needs its own.

Consequence: v2 is gated on a per-repo mechanics reference existing, not just on the ui-driver seam. That's a second dependency the Status section doesn't list, and it's the one that actually controls when v2 is cheap.

Corollary for the "reuse MSW/fixtures?" open question: runtime browser interception and MSW/fixtures are different plumbing — test-time vs a live dev server. You may reuse fixture JSON shapes, but not the interception mechanism. An init-script interceptor needs zero app cooperation and works on any driver, which is why it's the portable technique to standardize on.

2. Scenario definitions should come from an upstream authoring artifact, not inline args/config

The open question "where do scenario definitions live" has a better answer than inline / config / fixtures: an upstream scenario-authoring step that produces a markdown plan enumerating each scenario, its setup/mock, the route, and the expected state under a skeptical stance. That yields a clean lineage where each command is a deep module with a thin handoff:

author scenarios   → (the WHAT: scenarios + mock setup + expected state)
   |
/ba:prove          → (CONSTRUCT each state + CAPTURE evidence)
   |
/ba:propose        → (SHIP: splice staged PNGs into the MR body)

Coupling should be pull, not push: prove leaves artifacts at a known path; propose detects and splices them. Don't make propose drive a browser — prove is iterative (re-snap, adjust mocks) and doesn't fit propose's one-shot compose-and-ship flow. This matches ce-demo-reel's "the caller integrates it" model.

The caveat that makes the lineage honest: mocked screenshots prove rendering, not the system

/ba:prove's stated signal is "objective — it works." But a screenshot of a mocked error/empty state proves only that the FE renders that state, not that the real system produces it. Without guardrails, /ba:prove becomes a false-confidence artifact generator. Two rules fall out:

• Label mocked evidence as mocked in the MR splice — a reviewer must be able to tell "FE rendered against a fabricated 500" from "we triggered a real 500."
• Prefer real state construction (seed data / real API calls) over mocks when feasible. For an evidence command specifically, a screenshot where the data actually flowed through the system is stronger evidence than a mocked one. Mock only when a state is genuinely unreachable otherwise (rare 5xx, races).

And since this drives a real browser through login/auth screens, secret-scanning matters more here than for terminal capture — credentials render on screen; set them outside the captured region and scan before any upload.