# Verify-Work — MVP Mode UAT Framing

> Loaded by `verify-work` workflow and `gsd-verifier` agent only when the phase under verification has `mode: mvp` in ROADMAP.md. Reframes UAT generation from technical checks to user-flow walk-throughs.

## Core rule

**Show expected, ask if reality matches** — same philosophy as standard verify-work (from `workflows/verify-work.md`). The MVP-mode change is WHAT gets shown:

- **Standard verify-work:** "The API endpoint at /users/register returns 201 with the new user's ID." → user confirms.
- **MVP verify-work:** "Open the registration page. Fill in 'name', 'email', 'password'. Click Submit. You should see your dashboard with your name in the header." → user confirms.

The user-flow form mirrors what a real user does: open, fill, click, see. No HTTP verbs, no JSON shapes, no error codes.

## When this framing applies

The framing fires when:
- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-tools query roadmap.get-phase --pick mode`).
- AND the phase has a user-story-formatted goal (set by `/gsd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."

If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `references/planner-mvp-mode.md`).

## Generated UAT script structure under MVP mode

The UAT script generated by `verify-work` under MVP mode has THREE sections, in this exact order:

### 1. User-flow walk-through (always first, always required)

Derive ordered steps from the phase's user-story goal:

1. The first step opens the entry point ("Open the app", "Navigate to /register", "Run `gsd mvp-phase 1`").
2. Each subsequent step is one user action: fill, click, type, observe.
3. The final step asserts the user-visible outcome from the `[outcome]` clause of the user story.

Format each step as: "**Step N: [action]** — Expected: [what the user should see]". The user responds with one of:
- `yes` / `y` / `next` / empty → step passes
- Anything else → step is logged as an issue, and the script halts (do not proceed to step N+1 with a broken N).

If ALL user-flow steps pass, advance to section 2. If any step fails, the verdict is FAIL — do not run technical checks.

### 2. Technical checks (only if section 1 passes)

After the user flow passes, run the technical checks that would normally run in non-MVP mode:
- API endpoint schema verification (if the phase shipped APIs)
- Error state behavior (4xx, 5xx codes; invalid input handling)
- Edge cases (empty data, large data, concurrent requests if applicable)
- Cross-browser / cross-runtime checks (if applicable)

These are the same checks `verify-work` would run without MVP mode — just deferred until the user flow proves the slice actually works for a user.

### 3. Coverage check (always last, always required)

Verify that the user-story `[outcome]` clause is observably true in the codebase:
- If the outcome is "I can access my dashboard", verify a dashboard route exists and renders for an authenticated user.
- If the outcome is "I can bulk-import contacts", verify the import path produces persisted records.

Coverage is a goal-backward check: "did this phase deliver what its user story promised?" — sourced from the existing `gsd-verifier` agent's goal-backward methodology, narrowed to the user story.

## Anti-patterns to reject under MVP mode

- **Lead with technical checks.** "Step 1: GET /api/users/me returns 200." Reject. The user does not see API endpoints. Reorder so a user action comes first.
- **Schema-as-feature.** "User has a `name` field on the User model." Reject. The user does not see database fields. Express the same check as a user-visible outcome ("the user's name appears in the dashboard header").
- **Skip user flow because the test passed.** The unit test passing in CI is not evidence that the user flow works. The user-flow walk-through is mandatory under MVP mode even when all unit tests are green.

## Compatibility with existing verify-work philosophy

The "show expected, ask if reality matches" model is preserved. The user still types `yes` / `next` / empty to advance. The UAT.md state file format is unchanged. Only the WHAT changes — under MVP mode, the "expected" is a user-visible outcome rather than a technical assertion.

## Output: VERIFICATION.md changes under MVP mode

The `gsd-verifier` agent produces `VERIFICATION.md`. Under MVP mode, the report adds a top-level "User Flow Coverage" section that maps each step of the user story to evidence in the codebase:

```markdown
## User Flow Coverage

User story: «As a new user, I want to register and log in, so that I can access my dashboard.»

| Step | Expected | Evidence | Status |
|------|----------|----------|--------|
| Register | Form at /register accepts name/email/password | src/app/register/page.tsx:12 (form component) | ✓ |
| Submit | Persists user, redirects to /dashboard | src/api/register/route.ts:34 (db.insert + redirect) | ✓ |
| See dashboard | Dashboard page renders, shows user's name | src/app/dashboard/page.tsx:8 (greeting line) | ✓ |
| Outcome | "Access my dashboard" — user lands on a populated page | dashboard route + greeting both verified above | ✓ |
```

Standard technical-check sections of VERIFICATION.md remain (API verification, error handling, etc.) but are appended below "User Flow Coverage", not above.
