Snapshots and review

A snapshot is the evidence a command retains. It might be a browser screen, a terminal’s output or a set of database rows. Your agent compares that evidence with an earlier run and checks the change against your application’s rules.

Ask your agent:

Add snapshots at the points that explain this journey. Run it, inspect the changed screens and outputs, and fix regressions within the scope of my change. Show me the evidence and anything still unresolved before preparing the PR.

Browser screens

Use a named browser snapshot after the relevant assertion:

site.expect selector="[data-testid=invitation-form]"
site.snapshot name="team-invitation" selector="[data-testid=invitation-form]"

The name identifies the checkpoint across runs. Omit selector for the viewport, or select one visible element with stable bounds. Missing or ambiguous targets fail without a viewport fallback. See the Browser plugin for all capture arguments, timeouts and animation behavior.

The example below shows why a passed assertion still benefits from review: the invitation form exists, but the role selector disappeared during a copy change.

app.reflow.io

reflow / Team invitationsIllustrative example

Change SummaryAgent review

Change Summary

Update invitation copy

1 changed screen

invite-memberPassed

team-invitation/settings/team

Beforemain

Afterthis change

Capturing screenshot

The test passed. The screen changed.site.snapshot

Agent reviewOutside scope

The role selector disappeared.

This PR changes invitation copy. Owners still need to choose a role before sending an invitation.

team-invitationteam-access.md

Agent review / role change outside scope

Command output

LocalBash and DockerUbuntu retain command results, including standard output, standard error and exit status. Wrap an application CLI command in a flow:

worker.bash command="./bin/fulfill order-1042"

There is no extra screenshot command for a terminal. The command’s retained output is its evidence. Here, both versions exit successfully, but one stops returning tracking information. See LocalBash or DockerUbuntu for connection settings, command arguments and file capture.

reflow — terminal

Bash · fulfillment workerIllustrative example

fulfill-order.mdLocalBash

worker.bash
command="./bin/fulfill order-1042"

Your application command. Its result becomes a snapshot.

Beforeexit 0

stdout.txt order: 1042 status: dispatched tracking_number:
TRK-1042

stderr.txtempty

Afterexit 0

stdout.txt order: 1042 status: dispatched

tracking_numberMissing from output

stderr.txtempty

≠State and evidence changed

Exit code

0 → 0

Standard output

Changed

Both commands succeeded. The saved output differs.

Agent’s review note

“The worker still reports ‘dispatched’, but no longer returns a tracking number. Can the shipment notification still include a tracking link?”

Evidence: before + after / stdout.txt

Agent review / tracking number missing

Database rows

A query can capture the business state behind the screen:

db.query sql="SELECT id, status, refunded FROM orders ORDER BY id" key="id" checkpoint="orders"

Use a unique, non-null key for stable row ordering. The snapshot retains query rows; your agent relates the difference to the application’s refund rules. See the PostgreSQL plugin for setup, limits and write controls.

app.reflow.io

reflow / PostgreSQL · refund checkIllustrative example

Change SummaryAgent review

verify-refund.mddb: PostgreSQL

db.query sql="SELECT id, status, refunded
FROM orders ORDER BY id"
key="id" checkpoint="orders"

orders / rows.jsonEarlier runCurrent run

id key	status	refunded
1041	paid	0.00
1042 →	refunded	25.0020.00
1043	paid	0.00

3 rows retained · amounts in USD

Retained before → after1042

refunded25.00→20.00

Agent review · examplerefunds.md

Full refunds return the entire $25.00 payment.

The order says refunded. $5.00 is missing. The captured rows show $20.00 returned. Check the refund amount before merging.

Agent review / refund is $5 short

Choose the evidence that matters

Command	Retained evidence
site.snapshot name="…" selector="…"	A named screenshot of one element; omit selector for the viewport.
worker.bash command="…"	Command output, errors and exit status.
db.query … checkpoint="…"	Query result rows.
Custom plugin command	The state and artifacts declared by that provider.

These are command excerpts. Declare aliases, private bindings and exact plugin pins in your flow; see Write a flow. Use list_plugins to inspect the installed command schemas. Every plugin invocation returns a terminal snapshot, but only some commands capture a screen or a named review checkpoint. A click’s result does not replace an intentional screenshot of the outcome.

All visual examples on this page are illustrations. Reflow retains the exact originals from your actual execution; a comparison must not substitute an illustration or silently overwrite them.

Run, review and repair

reflow plan
reflow apply
reflow status
reflow dashboard

When earlier steps or covered source files change, the next plan automatically includes affected steps and their dependents. Apply runs that work. An unchanged, completed step can reuse its evidence; you do not need to taint it after every edit.

If the external application changed without a source or input change, request fresh evidence with reflow taint flow-name, then plan and apply. Your agent can select flow-name#step-name to start from a particular step; Reflow also includes affected dependents and the steps needed to reconstruct a browser session.

A difference is a question for your agent to investigate. It can update an obsolete test or fix a product regression, rerun the affected work and show the resulting delta. See Repair and rerun for that workflow.

Explicit visual assertions

For a deliberate approved-image contract, the RFL snapshot checkout threshold="2%" command additionally compares against an approved baseline using SSIM. It reports new without one; a mismatch fails that checkpoint. The default threshold is 1%. This is a separate contract from comparing two executions.

Assert application readiness first. settle="500ms" bounds waiting for finite animations; the default is two seconds, maximum ten seconds. A timeout retains the capture and fails without comparing an unsettled image. Looping animations are not frozen or masked. See the snapshot reference.

Neither a visual difference nor a new image is permission to change the baseline. Review originals before an authorized owner accepts an expectation. Agent repair preserves the original failure; it does not turn a mismatch into a passing result by approving it. A PR can compare changed evidence without adopting a baseline.