/verify-work

name: verify-work
description: Validate built features through conversational UAT
argument-hint: "[phase number, e.g., '4']"
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
  - Edit
  - Write
  - Task

Objective

Validate built features through conversational testing with persistent state.

Purpose: Confirm what was built actually works from the user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for re-execution.

Output: `{phase_num}-UAT.md` tracking all test results. If issues found: diagnosed gaps and fix plans ready for `/execute-phase`.

Context

Phase: $ARGUMENTS (optional)

• If provided: test specific phase (e.g., "4")
• If not provided: check STATE.md for active phase, or ask user

Process

**Step 1 — Load Phase Context**

Read:

• `.planning/phases/{phase}/SUMMARY.md` files (what was built)
• `.planning/REQUIREMENTS.md` (what was required)
• `.planning/ROADMAP.md` (phase goal)
• `.planning/phases/{phase}/{phase_num}-UAT.md` if a prior session exists (resume from last passing test)

**Step 2 — Derive Test Scenarios**

From the phase SUMMARY.md and requirements, derive a list of test scenarios:

• One scenario per user-facing behavior
• Ordered from most critical to least
• Include happy path and key error cases

**Step 3 — Present Tests One at a Time**

For each scenario: 1. Describe the test in plain language: "Try doing X. You should see Y." 2. Wait for user's response (pass / fail / skip / notes) 3. Record result in UAT tracking

Do NOT present multiple tests at once. Do NOT ask the user to run commands.

**Step 4 — Handle Failures**

For each failed test: 1. Diagnose the failure: read relevant code to understand root cause 2. Describe the issue clearly 3. Create a gap closure PLAN.md file in the phase directory:

• Filename: `{phase_num}-gap-{N}-PLAN.md`
• Frontmatter: `gap_closure: true`
• Content: targeted fix for the specific failure

**Step 5 — Write UAT Report**

Create or update `.planning/phases/{phase}/{phase_num}-UAT.md`:

# Phase [X]: UAT Report

**Date:** [date]

## Results

| # | Scenario | Status | Notes |
|---|----------|--------|-------|
| 1 | [scenario] | PASS/FAIL | [notes] |

## Gap Plans Created

- `{phase_num}-gap-01-PLAN.md`: [what it fixes]

## Summary

X/Y tests passed.

**Step 6 — Guide Next Steps**

If all tests pass: > "All tests passed. Phase [X] is complete. Run `/plan-phase {next}` to begin Phase [next]."

If tests failed: > "Found [N] issue(s). Gap plans created. Run `/execute-phase {phase} --gaps-only` to apply fixes."

Success Criteria

• [ ] Phase context loaded (SUMMARY.md, requirements, roadmap)
• [ ] Test scenarios derived from requirements and summaries
• [ ] Tests presented one at a time with clear instructions
• [ ] Failures diagnosed and gap PLAN.md files created
• [ ] UAT report written with all results
• [ ] User knows next step