Uat Walkthrough

---
description: Walk through a pending UAT file test-by-test with the user
argument-hint: <path/to/uat-file.md, number-slug, or description>
---
**Always obey `.docs/guides/mcp-tools.md`. Read it now if not already in context.**
**Always obey `.docs/guides/task-lifecycle.md`. Read it now if not already in context.**
**Run `/primer` first if you have not already this session.**


# UAT Walkthrough

Interactively walk through each test in a pending UAT file, presenting instructions to the user and recording pass/fail results.

---

**UAT File**: $ARGUMENTS

---

## Pipeline Context

This command is part of the task lifecycle: `/add-task` → `/tackle` → `/uat-generator` → **`/uat-walkthrough`**

Tasks remain in `.docs/tasks/active/` until all UAT tests pass, at which point this command moves them to `.docs/tasks/completed/`. UAT files are generated by `/uat-generator` and placed in `.docs/uat/pending/`.

---

## Cycle Overview

This command runs in a continuous loop, presenting tests in typed batches:

┌─────────────────────────────────────────────────────────────────────────────┐ │ 1. READ & PARSE → 1.5. MODE SELECT → 2. FIND NEXT BATCH → 3. PRESENT │ │ ↑ (first cycle) │ │ │ │ ┌─────────┼──────────┐ │ │ │ 3A. API 3B. UI 3C. Manual │ │ │ (auto-run) (batch) (single) │ │ │ └─────────┼──────────┘ │ │ │ ↓ │ │ │ 4. RECORD VERDICTS (per test) │ │ │ / \ │ │ │ [fix now] [other] │ │ │ ↓ ↓ │ │ │ FIX → RE-TEST UPDATE │ │ │ ↓ │ │ │ └──────────────── 5. UPDATE FILE ←───────┘ │ └─────────────────────────────────────────────────────────────────────────────┘

---

## Step 1: Read and Parse the UAT File

### Resolve the UAT File

Parse `$ARGUMENTS` to locate the UAT file:

1. **If a file path is provided** (e.g., `.docs/uat/pending/3-user-auth.uat.md`):
   - Use the path directly

2. **If a number-slug is provided** (e.g., `3-user-auth`):
   - Search `.docs/uat/pending/` for `<number-slug>.uat.md`
   - If not found, also check `.docs/uat/completed/` as a fallback
   - If not found in either, STOP and report the error

3. **If only a description or number is provided** (e.g., `user auth` or `3`):
   - Search `.docs/uat/pending/` for a matching UAT file
   - If ambiguous, list matches and ask the user to clarify
   - If no match found, STOP and report the error

Use the resolved file path for all subsequent steps.

### Parse the UAT File

- Read the resolved UAT file
- If the file does not exist or is empty, STOP and report the error
- If the file is not in `.docs/uat/pending/`, warn the user and confirm they want to proceed
- Parse the structure to identify:
  - **Test sections**: Headings matching `### UAT-*` patterns (e.g., `### UAT-API-001:`, `### UAT-UI-002:`)
  - **Prerequisites**: Items under `## Prerequisites`
  - **Test status**: Each test ends with `- [ ] Pass` (pending), `- [x] Pass` (passed), `- [FAIL: ...] ...` (failed), `- [FIXING: ...] ...` (fix in progress), or `- [SKIP: ...] ...` (user skipped)
- Count totals: passed, failed, pending, skipped

---

## Step 1.5: Mode Selection (on first cycle only)

After parsing, if there are **any failed tests** (`[FAIL]`), present the mode choice inline:

This UAT has N failed and M pending tests. Failed first / Pending only / Failed only?

- **Failed first** — Re-test failed tests, then continue with pending
- **Pending only** — Skip failed tests, only walk through untested items
- **Failed only** — Only re-test failed tests, skip pending

Store the chosen mode for the duration of this walkthrough. If there are **no failed tests**, skip this step entirely and proceed normally (pending only).

---

## Step 2: Find the Next Test Batch

### Prerequisites (always first, regardless of mode)
- If any prerequisites are unchecked (`- [ ]`), present **all of them at once as a batch** before tests — do not present them one at a time

### Test Selection (based on chosen mode)

| Mode | Order |
|------|-------|
| **Failed first** | All `[FAIL]` tests in document order → then all `- [ ] Pass` tests in document order |
| **Pending only** | Only `- [ ] Pass` tests in document order (skip `[FAIL]`) |
| **Failed only** | Only `[FAIL]` tests in document order (skip `- [ ] Pass`) |

When re-testing a failed test, first **reset its status** from `- [FAIL: ...]` back to `- [ ] Pass` in the file before presenting it.

### Batching Rules

Tests are presented in **batches of up to 5** based on their type:

1. **Classify each test** by type:
   - **API/CLI test**: Contains `curl`, `http`, `wget`, or code blocks with shell commands in the Steps or Expected Result, OR has an `Endpoint:` metadata field
   - **UI test**: Has `UAT-UI-*` prefix, or has `Page:` / `Components:` metadata
   - **Manual test**: Everything else (edge cases, integration logic, etc.)

2. **Collect the next batch** from the eligible tests (per mode):
   - Take the next **up to 5 consecutive tests of the same type** (API/CLI, UI, or Manual)
   - If the next test switches type, start a new batch with the new type
   - A batch can be smaller than 5 if fewer remain or the type changes

3. **Route the batch** to the appropriate presentation flow:
   - API/CLI batch → Step 3A (auto-execute)
   - UI batch → Step 3B (batched manual)
   - Manual batch → Step 3C (single manual, one at a time —