Flow Diff

Compare the latest walk snapshot against previous runs to detect regressions and improvements.

Usage

/flow-diff sign-up              # latest vs previous
/flow-diff sign-up --history 5  # trend over last 5 runs

Process

1. Find Snapshots

List all snapshot directories for the flow:

ls -d .flowchad/snapshots/*-{flow-name} | sort

Need at least 2 snapshots to diff. If only 1 exists, tell the user to walk again after making changes.

2. Load Results

Read results.json from the two most recent snapshots (or N for --history).

3. Compare Step-by-Step

For each step, compare across snapshots:

Check	Method	Alert
Status change	Compare status field	Any change (pass↔fail, pass↔error)
Timing regression	Compare timing_ms	>50% slower than previous
Timing improvement	Compare timing_ms	>25% faster than previous
New failure	Step was pass, now fail/error	Always alert
Fixed	Step was fail/error, now pass	Always note (positive)
New step	Step exists in latest, not in previous	Note (flow changed)
Removed step	Step in previous, not in latest	Note (flow changed)

4. Visual Comparison

For steps with status changes or significant timing differences, present screenshots side-by-side:

### Step 3: click submit

| Before (Mar 18) | After (Mar 20) |
|---|---|
| step-03-click.png | step-03-click.png |
| ✓ pass, 1.2s | ✗ fail, timeout |

Read both screenshots and describe the visual difference (e.g., "button is now disabled", "error modal appeared", "loading spinner stuck").

5. Trend Analysis (--history)

When multiple snapshots available, track trends:

### Timing Trend: step 1 (navigate /signup)

Run 1 (Mar 15): 1.2s
Run 2 (Mar 17): 1.4s
Run 3 (Mar 19): 2.1s ⚠️
Run 4 (Mar 20): 2.8s ⚠️⚠️
Trend: DEGRADING (+133% over 4 runs)

### Pass Rate Trend

Run 1: 4/4 (100%)
Run 2: 3/4 (75%)
Run 3: 4/4 (100%)
Run 4: 3/4 (75%)
Trend: UNSTABLE (flapping step 3)

6. Output

Print a diff report:

## Flow Diff: sign-up
**Comparing:** 2026-03-18 → 2026-03-20

### Regressions
- ⚠️ Step 3 (click submit): pass → fail (button not found)
- ⚠️ Step 1 (navigate): 1.2s → 2.8s (+133%, threshold: 2s)

### Improvements
- ✓ Step 2 (fill email): 0.8s → 0.15s (-81%)

### Unchanged
- Step 4 (fill password): pass, 0.12s (stable)

### Summary
| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Pass rate | 100% | 75% | -25% |
| Total time | 3.5s | 5.9s | +69% |
| Slow steps | 0 | 2 | +2 |

Suggest /flow-report sign-up for detailed analysis of current state.