Reviewing flow changes
When someone changes a .flow.md file in a pull request — adds a new
scenario, tweaks the prose of an existing one, or refines an
assertion — the prose change isn’t the whole story. The compiled step
list (the .flow.json next to the prose) also changes, and that’s
what actually runs against the app.
You don’t have to read the JSON. CI does the translation for you and posts a Markdown comment on the PR with a before/after table of the compiled steps in plain English. Reviewing a flow change as a non-engineer is reading that table and answering one question: “do these steps still match what I’d want a new teammate to do?”
What the PR comment looks like
When a contributor pushes a change to a .flow.md, CI regenerates the
sibling .flow.json and posts a comment that looks like this:
klera flow diff —
flows/sign-in-and-reorder.flow.md
# Before After 1 Sign in with email pm@example.comand password***Sign in with email pm@example.comand password***2 Wait for the home screen to settle Wait for the home screen to settle 3 Tap “Orders” Tap “Orders” 4 Tap the first row in the orders list Tap the first row in the orders list 5 Tap “Reorder” Tap “Reorder” 6 Assert the cart drawer is visible Assert the cart drawer is visible — no step Assert the cart total reads “$84.20” Cache hash changed; 1 step added, 0 removed, 0 modified.
A few things to notice:
- The table is compiled from the new prose. You’re reading what the flow will do, not the prose itself.
- The hash line at the bottom is plumbing. It tells engineering that the cache regenerated cleanly. You can ignore it.
- Sensitive values (passwords, API keys) are masked. They never appear in the comment.
What you’re looking for
A flow review is two questions, in order:
1. Does the new step list still describe the scenario you’d want?
Skim the After column top to bottom. Read each row out loud the way you’d describe it to a new hire. If at any point you’d say “wait, that’s not what I meant”, the prose is the thing to fix — leave a comment on the PR pointing at the row.
2. Are the changed rows the changes the PR claimed to make?
The PR description says “adds a check that the cart total is right after reorder”. You’d expect to see a new “Assert the cart total” row, and the rest of the rows unchanged. If you see other rows changing — a tap that moved, an assertion that disappeared, a screen the flow now skips — that’s worth flagging. Sometimes a small prose edit has a bigger effect on the compiled steps than the author expected.
You don’t need to verify that the flow is “correct” in the engineering sense. The matcher does that when the flow runs. You’re reviewing whether the scenario description still matches what the team wanted to test.
A worked example
Here’s a real-shaped review walkthrough.
A PM opens a PR
She edits flows/checkout.flow.md to add a check that the cart total
reads correctly after applying a coupon. Her prose change:
# Checkout with a coupon applies the discount
Sign in. Add the demo item to cart. Open the cart drawer. Apply the
coupon code "SAVE10". Assert that the cart total reads "$45.00"
instead of the original "$50.00". Tap Checkout. Confirm the order
screen also shows "$45.00".(The previous version of the prose stopped at “Apply the coupon code ‘SAVE10’” without asserting anything.)
CI regenerates the cache
A few seconds after the push, the klera bot posts:
klera flow diff —
flows/checkout.flow.md
# Before After 1 Sign in with the demo account Sign in with the demo account 2 Tap “Add to cart” on the demo item Tap “Add to cart” on the demo item 3 Open the cart drawer Open the cart drawer 4 Tap “Apply coupon” Tap “Apply coupon” 5 Type “SAVE10” into the coupon field Type “SAVE10” into the coupon field 6 Tap “Apply” Tap “Apply” — no step Assert the cart total reads “$45.00” 7 Tap “Checkout” Tap “Checkout” — no step Assert the order screen total reads “$45.00” Cache hash changed; 2 steps added, 0 removed, 0 modified.
A PM teammate reviews
She reads through the After column. The first six rows are the same as before. Two new assertions land at the right places — one on the cart drawer, one on the order screen. The PR description claimed it was adding a check that the discount applies; the diff shows two new checks that the totals match. That’s a slightly stronger version of what was promised, and the wording reads naturally.
She approves the PR with a comment: “Diff looks right. The two new asserts are exactly what we agreed in the spec — nice catch on also checking the order screen.”
Engineering merges
The merged PR runs against CI’s full flow suite. The flow passes. The new assertions are now part of the regression set — if a future change breaks the discount, this flow will fail and the report will name it.
When to ask the author to clarify
Some patterns in a flow diff are worth a comment back to the PR author:
- A row changed that the PR didn’t promise to change. The author may have phrased something ambiguously and the compiler picked a different interpretation. “You changed the assertion text — was that intentional?” usually surfaces it.
- A row disappeared. If the After column has fewer rows than the Before column, ask why. Sometimes the author legitimately simplified a flow; sometimes a sentence got dropped accidentally.
- An assertion turned into a tap, or vice versa. Steps shouldn’t change kind from a small prose edit. If row 4 was an assertion before and a tap now, something is off.
- The cache hash changed but no rows changed. This is harmless (it usually means the underlying compiler version moved) but worth a quick “merge when CI is green” comment so the author isn’t left guessing.
What you don’t need to review
The .flow.json file itself shows up in the file list of the PR. It’s
machine-generated; ignore it. The Markdown comment from CI is the
human-readable view of the same change. If for some reason CI didn’t
post a comment, the engineer-track
prose flows page describes how to
regenerate the diff locally.
The bottom line: you review prose, you review the step-list diff, and you trust the matcher to handle the rest. If the flow ever fails after merge, the report will tell you what happened.