uat-walk

name	uat-walk
description	Walk through a pending UAT file test-by-test with the user
category	executing
model	claude-sonnet-4-6
argument-hint	<path/to/uat-file.md, number-slug, or description>
disable-model-invocation	false
user-invocable	true

Always obey .docs/guides/mcp-tools.md. Read it now if not already in context. Always obey wiki/work/tasks/lifecycle.md. Read it now if not already in context. Run /primer first if you have not already this session.

UAT

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: /task-add → /tackle → /uat-generate → /uat-walk

Tasks remain at their stable path in wiki/work/tasks/ until all UAT tests pass, at which point this command flips their status: to done (files never move). UAT files are generated by /uat-generate and placed in wiki/work/uat/.

---

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) (compact) (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., wiki/work/uat/UAT-003-user-auth.md):

   • Use the path directly

2. If a number-slug is provided (e.g., UAT-003 or 003-user-auth):

   • Search wiki/work/uat/ for a matching file (files never move — no completed/ subdir)
   • If not found, STOP and report the error

3. If only a description or number is provided (e.g., user auth or 3):

   • Use Serena list_dir wiki/work/uat/ 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 wiki/work/uat/, 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, decide the mode based on what's present. Only ask the user when there is a genuine ambiguity — if only one mode is sensible, pick it silently and proceed.

Failed count	Pending count	Action
0	any	Skip this step. Proceed with Pending only silently.
≥1	0	Skip this step. Proceed with Failed only silently (Failed first and Failed only are equivalent when no pending tests remain). Briefly note the auto-choice in your status line, e.g. "3 failed tests, no pending — re-running failed tests."
≥1	≥1	Ask the user inline (see prompt below).

When asking is required, 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 (or auto-selected) mode for the duration of this walkthrough.

---

Step 2: Find the Next Test Batch

Prerequisites (always first, regardless of mode)

• If any prerequisites are unchecked (- [ ]), attempt to auto-verify each one before presenting it to the user:
  • For runnable checks (e.g. "dev server running at localhost:4321", "database migrated"), attempt to verify with a single deterministic command (curl, pg_isready, a file existence check). One Bash call per prerequisite.
  • For descriptive-only prerequisites (e.g. "test data loaded"), mark them as unverifiable — they must be confirmed by the user.
• After auto-checking, present all prerequisites at once grouped by status:
  • Auto-verified ✅: ones that passed the check (user can ignore these unless they notice something wrong)
  • Needs confirmation ❓: ones that are unverifiable or whose check failed
• If all prerequisites are auto-verified with no failures, note "All prerequisites verified automatically" and proceed without asking the user
• If any prerequisite fails or is unverifiable, present those to the user for confirmation before proceeding

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 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):

   • API/CLI: take the next up to 5 consecutive API/CLI tests
   • UI: take the next up to 3 consecutive UI tests — kept small so all fit on screen
   • Manual: take exactly 1 test — manual tests are never batched
   • If the next test switches type, start fresh with the new type

3. Route to the appropriate presentation flow:

   • API/CLI batch → Step 3A (auto-execute, up to 5)
   • UI batch → Step 3B (compact batch, up to 3)
   • Manual test → Step 3C (single, one at a time — no batching)

Completion Check

• If no more tests match the current mode:
  • A UAT file is complete when no tests have a blocking status. Blocking statuses are [FAIL: ...] and [FIXING: ...]. Non-blocking statuses are [x] Pass (passed) and [SKIP: ...] (user decided the test is not necessary). Only - [ ] Pass (untested) is ambiguous — it is non-blocking only if the current mode excluded it (e.g., "Failed only" mode skips pending tests).
  • Proceed to the Completion section at the bottom of this skill and execute Post-Walkthrough Actions in full. Do not STOP here — all file moves, index updates, roadmap auto-checkoff, and ADR linkage checks happen there.

---

Step 3: Present and Execute the Test Batch

All presentation uses markdown bold (**Label:**) for labels — Claude Code renders bold in the terminal. Always show current progress counts.

---

Step 3A: API/CLI Test Batch (Auto-Execute)

API/CLI tests are executed automatically — no user prompt before running. Present the batch, run all commands, and show results.

Presentation & Execution Flow

1. Present the batch header:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
API TEST BATCH [tests 3–7 of 18]
**Progress:** 2/18 passed · 0 failed · 16 remaining
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2. For each test in the batch, execute and present results inline:

───────────────────────────────────────────
**[3 of 18] UAT-API-001: Create Position**
**Endpoint:** POST /api/positions
**Description:** Verify creating a new position returns 201

▶ **COMMAND:**
  curl -sS -X POST 'http://localhost:4321/api/positions' -H 'Content-Type: application/json' -d '{"title":"Engineer"}'

▶ **EXPECTED:**
  - HTTP 201
  - Response body contains `id` and `title: "Engineer"`

▶ **ACTUAL:**
  - HTTP 201
  - Response: {"id": 1, "title": "Engineer", "created_at": "2026-04-04T..."}

▶ **RESULT:** ✅ Matches expected
───────────────────────────────────────────

Layout rule: EXPECTED must always appear immediately above ACTUAL with no other content between them — never side-by-side prose, never separated by intervening output. The user must be able to compare the two blocks at a glance without scrolling. If a response body is truncated for display, truncate it inside the ACTUAL block; do not move it elsewhere.

Assessment rule (mandatory, applies on every presentation including retests): After the ACTUAL block, always output a ▶ **RESULT:** line with a clear indicator:

• ✅ Matches expected — when all expected criteria appear to be met
• ❌ Does not match expected — <one-line reason> — when the output diverges (wrong status code, missing field, error body, etc.)

This indicator is the agent's observation, not a verdict — the user still issues the final pass/fail. It must appear on every API/CLI result presentation, including after a Fix Now retest.

3. Execute tests one at a time, one Bash invocation per test. Run the test, capture and present its result, then run the next test. Never batch multiple tests into a single Bash call. The walkthrough's "batch" concept refers to presentation grouping, not command chaining.

4. Capture for each test:

   • HTTP status code (curl prints it as part of the response when using -i, or use -sS and rely on the response body for status indication)
   • Response body (truncate display to ~50 lines if very large, but do not write to a temp file just to read it back)
   • Any errors (connection refused, timeout, etc.)

5. If a command fails to execute (connection refused, timeout, etc.) OR the actual result does not match the expected result (e.g., HTTP status mismatch, error in response body, missing fields, exception output):

   • Show the error or mismatch in the ACTUAL section, then show ▶ **RESULT:** ❌ Does not match expected — <reason>
   • STOP immediately. Do NOT continue executing the remaining tests in the batch.
   • Ask the user inline for that single failing test: Pass / Fail / Fix now / Skip?
   • Wait for explicit direction. The agent never moves on to another test after a failure without explicit user direction.
   • Once the user has responded, apply the verdict (Step 4/5), then resume executing the remaining tests in the batch from where you halted

6. After all tests in the batch are executed without failure, present the batch results summary and ask for verdicts (see Step 4A)

Rules

• Never ask "Run / Manual / Skip?" — always auto-execute
• Never auto-judge pass/fail — the user decides after seeing actual vs expected
• Halt on failure (mandatory): If a test's auto-executed result errors out OR the actual output clearly does not match the expected result (HTTP code mismatch, error in response body, exception, missing required fields), STOP the batch immediately at that test. Ask the user Pass / Fail / Fix now / Skip? for the failing test and wait for an explicit reply before running any further tests. The agent never moves on after a failure without explicit direction. Observing a mismatch is not the same as judging pass/fail — the user still issues the verdict; the agent only halts so the user can decide.
• Extract commands from the test's Steps and Expected Result sections (typically the **Command**: block written by /uat-generate)
• Run the command as-is. Do not wrap it, decorate it, or rewrite it.
• If a test has no extractable command but was classified as API/CLI, present it as a manual test instead (fall back to Step 3C for that individual test)

⛔ Forbidden Bash Patterns When Running API Tests

These patterns trigger user approval prompts on every invocation, slow the walkthrough to a crawl, and obscure the real curl output. Do not use them. Ever.

❌ Forbidden	Why	✅ Do this instead
Multiple curl calls in one Bash invocation	Chained commands trigger approval prompts; agent loses per-test feedback loop	One Bash call per test, run sequentially
echo "=== UAT-API-001 ===" banners	Approval prompt; clutters output	The presentation header (Step 2) is the banner
&&, ;, || chaining between commands	Same as above	Separate Bash calls
-w "\nHTTP %{http_code}\n" format strings	The user reads response directly; this is line noise	Just curl -sS
-o /tmp/api1.json then head -c 800 /tmp/api1.json	Approval prompt; pointless indirection	Print response to stdout, truncate display in your message
--max-time 90 or other defensive flags	Defaults are fine; failing fast is good	Plain curl -sS
Pre-assigning TOKEN=..., STRATEGY_ID=... then using $TOKEN in the curl	Multi-line shell scripts trigger approval prompts and hide values	Inline the literal value into the curl command on a single line
curl ... \ line continuations	Single-line commands are easier to read in the approval dialog	One long line per curl
Piping into head, tee, or output redirection	All trigger approval prompts	A single | jq '.' or | jq '<projection>' is permitted; nothing else

The rule of thumb: each Bash call should contain exactly one program invocation (one curl, optionally one jq pipe stage). If your bash command has more than one statement, more than one curl, an echo, a ;, or a &&, you are doing it wrong. Run the test again as a single clean curl.

If the previously generated UAT file contains any of these forbidden patterns in its **Command**: blocks, clean them up before running — do not faithfully execute a malformed command just because it was written that way. The clean curl style is documented in lib/skills/uat-generate/SKILL.md "Curl command standards".

---

Step 3B: UI Test Batch (Compact)

UI tests are presented in batches of up to 3, written compactly so the entire batch fits on screen without scrolling. Every test entry must be brief — a one-line description, abbreviated steps, and a one-line expected result. Omit preamble, rationale, and prose padding.

Presentation Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UI TEST BATCH [tests 8–10 of 18]
**Progress:** 7/18 passed · 0 failed · 11 remaining
**Page:** http://localhost:4321/strengths
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[8] UAT-UI-001 — Strength Panel Layout
  Steps: Navigate to /strengths · Verify panel is on the right
  Expected: Right-aligned, no horizontal scroll
───────────────────────────────────────────
[9] UAT-UI-002 — Strength Panel Empty State
  Steps: Clear strengths · Navigate to /strengths
  Expected: "No strengths yet" message visible
───────────────────────────────────────────
[10] UAT-UI-003 — Strength Card Display
  Steps: Add a strength · Check the card
  Expected: Card shows title and description
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Verdicts for UI batch (tests 8–10)?
  [8] Pass / Fail / Fix now / Skip?
  [9] Pass / Fail / Fix now / Skip?
  [10] Pass / Fail / Fix now / Skip?

Rules

• Maximum 3 tests per batch — never exceed 3 UI tests in a single presentation
• One line per field — description, steps (dot-separated), expected result; no multi-line blocks
• Group by page — if all tests share the same Page: URL, show it once in the batch header
• Steps as a single line — condense numbered steps into a short dot-separated sequence
• After presenting the batch, ask for verdicts inline (as shown above) and proceed to Step 4B

---

Step 3C: Manual Test (Single)

Tests that don't fit API/CLI or UI categories are presented one at a time (no batching):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TEST [14 of 18]: UAT-EDGE-003 — Concurrent Updates
**Progress:** 12/18 passed · 1 failed · 5 remaining
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Description:** Verify that concurrent updates to the same record don't cause data loss
**Scenario:** Two users edit the same position simultaneously

**STEPS:**
1. Open position #1 in two browser tabs
2. Edit the title in tab 1 and save
3. Edit the description in tab 2 and save

───────────────────────────────────────────
▶ **EXPECTED RESULT:**
- Second save either merges or shows a conflict error
- No silent data loss

After presenting, proceed to Step 4C for a single verdict.

---

Step 4: Record the User's Verdict

Prompt the user inline — do NOT use AskUserQuestion for verdicts. The approach varies by batch type.

⛔ MANDATORY VERDICT GATE

You MUST receive an explicit pass/fail/fix/skip verdict from the user for every single test before moving on. No exceptions.

• Batched tests (API/CLI Step 4A, UI Step 4B): ask for verdicts on all tests in the batch at once, in a single prompt. Then STOP and wait for the user's reply. Do not present the next batch, do not run more commands, do not call any other tools until the user has responded with verdicts that cover every test in the current batch. If the user's response leaves any test in the batch unaccounted for, ask a follow-up specifically for the missing tests — do not assume, do not default to pass.
• Single tests (manual Step 4C, fix-now re-tests): ask for the verdict immediately after presentation and STOP and wait. Do not present the next test until the user has answered for the current one.
• Auto-executed failures (API/CLI Step 3A): if a test errors out or its actual result clearly does not match the expected result, halt the batch immediately at that test. Ask Pass / Fail / Fix now / Skip? for the single failing test and STOP and wait. Do NOT execute the next test in the batch, do NOT proceed to the batch verdict prompt, and do NOT call any other tools until the user has given direction for the failing test. The agent never moves on after a failure without explicit user direction.
• Never auto-judge, infer a verdict from output, or move on "because the result looked fine." The user is the only authority on pass/fail.

This is a hard requirement, not a preference. Violating it invalidates the walkthrough.

---

Step 4A: API/CLI Batch Verdicts

After executing and presenting all tests in the batch, collect verdicts per test:

**Verdicts for API batch (tests 3–7):**
  [3] UAT-API-001: Create Position — Pass / Fail / Fix now / Skip?
  [4] UAT-API-002: Get Position — Pass / Fail / Fix now / Skip?
  [5] UAT-API-003: Update Position — Pass / Fail / Fix now / Skip?
  [6] UAT-API-004: Delete Position — Pass / Fail / Fix now / Skip?
  [7] UAT-API-005: List Positions — Pass / Fail / Fix now / Skip?

The user can respond in any of these formats:

• All same: all pass, all p — applies the same verdict to every test in the batch
• Per-test: p p f fix s — space-separated verdicts in order
• Selective: 3: pass, 5: fail, rest pass — named overrides with a default
• Single: If only one word, apply it to all tests

Parse the response and apply verdicts. If ambiguous, ask for clarification.

---

Step 4B: UI Batch Verdicts

After the user has tested the UI batch, collect verdicts per test:

**Verdicts for UI batch (tests 8–10):**
  [8] UAT-UI-001: Strength Panel — Layout — Pass / Fail / Fix now / Skip?
  [9] UAT-UI-002: Strength Panel — Empty State — Pass / Fail / Fix now / Skip?
  [10] UAT-UI-003: Strength Card — Display — Pass / Fail / Fix now / Skip?

Same response formats as Step 4A (all same, per-test, selective, or single).

---

Step 4C: Single Test Verdict

For manual (non-batched) tests, prompt:

Pass / Fail / Fix now / Skip?

The user will type their choice. Accept any unambiguous prefix (e.g., "p", "pass", "f", "fail", "fix", "s", "skip").

---

Verdict Actions (apply per test, regardless of batch type)

If Pass

• Mark the test: - [x] Pass <!-- YYYY-MM-DD -->

If Fail

• Ask a follow-up inline: "What went wrong? (optional, press Enter to skip)"
  • For batched fails: ask once per failed test, or accept a single note for all failures
• Mark the test: - [FAIL: <user's note or "No details provided">] <!-- YYYY-MM-DD -->

If Fix Now

• Ask inline: "What went wrong?"
• Resolve approach ambiguity before delegating (mandatory). The root cause and target component are usually clear from the test itself. The ambiguity that matters is how to fix it in the wider codebase — whether the fix has side effects, whether there are multiple valid approaches with different tradeoffs, or whether the safest fix path touches shared code. If any of those are unclear, STOP and ask before delegating. Do not hand a subagent an approach decision it shouldn't be making alone. Examples:
  • "There are two ways to fix this — clamp at the API layer or adjust the validation schema. Which fits better with the rest of the feature?"
  • "This fix would touch the shared <X> utility. Should I scope it narrowly to this test or update it globally?" If the fix path is unambiguous (one obvious change, no shared-code risk), proceed directly.
• Mark the test temporarily: - [FIXING: <user's note>] <!-- YYYY-MM-DD -->
• Process all non-fix verdicts first (pass/fail/skip in the batch), then handle Fix Now tests one at a time
• Delegate a fix to a subagent (see Fix Workflow below)
• After the subagent completes, reset status to - [ ] Pass and re-present this same test for the user to verify the fix
• The re-presented test follows the single-test verdict flow (Step 4C)

If Skip

• Ask a follow-up inline: "Reason for skipping? (optional, press Enter to skip)"
• Mark the test: - [SKIP: <user's reason or "User skipped">] <!-- YYYY-MM-DD -->
• Move to the next test

---

Step 5: Update the UAT File

After each verdict:

1. Update the test's status line in the file using the Edit tool — one Edit call per status line. Never use sed, awk, perl -i, or echo to flip status markers, even when many tests need updating in a row. One Edit call per test is correct; one sed is wrong (and triggers an approval prompt every time). See .docs/guides/mcp-tools.md "Common anti-patterns".
   • Replace - [ ] Pass with the appropriate marker (see Step 4)
2. Do NOT modify any other part of the test — only the status line changes

Example Updates

Pass:

Before: - [ ] Pass
After:  - [x] Pass <!-- 2026-03-03 -->

Fail:

Before: - [ ] Pass
After:  - [FAIL: Returns 401 instead of 200, token may be expired] <!-- 2026-03-03 -->

---

Fix Workflow

When the user selects "Fix now", delegate the fix to a general-purpose subagent via the Task tool:

Subagent Prompt Template

Fix a UAT test failure.

UAT File: <path>
Test: <UAT-ID> — <Test Name>
Failure: <user's description of what went wrong>

Test details:
<paste the full test section: endpoint/page, description, steps, expected result>

Instructions:
1. Use MCP Serena to find the relevant code for this test
2. Identify the root cause of the failure
3. Implement the fix
4. Run any available quality checks (linter, typecheck, tests)
5. Report what was changed and why

Fix Rules

⚠️ NEVER AUTO-PASS AFTER A FIX — this is the most important rule in the fix workflow.

• Max 1 fix subagent at a time — wait for it to complete before continuing
• After ANY fix (code or UI), you MUST:
  1. Reset the test status to - [ ] Pass
  2. Re-present the test to the user (Step 3)
  3. Ask the user for their verdict inline (Step 4) — Pass / Fail / Fix now / Skip?
  4. Only the user can mark a test as passing — the agent never decides pass/fail
• If the fix subagent reports failure or cannot resolve the issue, inform the user and present normal verdict options (Fail / Skip)
• The [FIXING: ...] marker is temporary — it must be replaced with either [x] Pass, [FAIL: ...], or [ ] Pass before moving to the next test
• A successful fix does NOT mean the test passes — the user must manually confirm

---

Step 6: Repeat the Cycle

After updating:

1. Return to Step 1 — Re-read the file to get current state
2. Find next batch — Step 2 (classify and batch tests)
3. Present — Step 3A/3B/3C (based on batch type)
4. Record — Step 4A/4B/4C (collect verdicts) — HARD STOP here until the user has given a verdict for every test in the current batch/single. Do not advance to the next batch or test until that is true.
5. Update — Step 5
6. Continue until all tests are resolved or user aborts

---

Completion

When the walkthrough ends (all tests resolved or user aborts), report:

Summary Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UAT WALKTHROUGH COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File:    wiki/work/uat/UAT-005-positions.md
Source:  wiki/work/tasks/TASK-005-positions.md

Results:
  ✅ Passed:  6
  ⚠️ Skipped: 1
  ❌ Failed:  2
  ❔ Pending: 0
  Total:     9

Failed Tests:
  • UAT-API-003: Delete Position — "Returns 500 instead of 204"
  • UAT-EDGE-001: Empty Positions — "Loading spinner never resolves"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Post-Walkthrough Actions

• All complete (no [FAIL] or [FIXING] markers remain — every test is [x] Pass or [SKIP: ...]):

  1. Flip UAT status: Edit status: pending (or in-progress) → status: passed; bump updated: to today in the UAT file's frontmatter.
  2. Flip task status: Read the UAT file's task: frontmatter to get the task ID (e.g. TASK-014). Open wiki/work/tasks/TASK-NNN-slug.md, edit status: in-progress → status: done; bump updated:.
  3. Remove rows from family indexes:
     • Remove the UAT's row from wiki/work/uat/index.md
     • Remove the task's row from wiki/work/tasks/index.md Use a single Edit call per file — never sed.
  4. Archive both files:
     • git mv wiki/work/uat/<UAT-file>.md wiki/work/uat/archive/<UAT-file>.md
     • Append UAT row to wiki/work/uat/archive/index.md: | [[UAT-NNN]] | Title | passed | YYYY-MM-DD |
     • git mv wiki/work/tasks/<TASK-file>.md wiki/work/tasks/archive/<TASK-file>.md
     • Append task row to wiki/work/tasks/archive/index.md: | [[TASK-NNN]] | Title | done | YYYY-MM-DD | Use Bash for git mv only. Use Edit for all index appends.
  5. Roadmap Auto-Checkoff — find all roadmaps with status: active in wiki/work/roadmaps/ (scan by frontmatter). For each:
     • Read the roadmap and look for checklist lines matching [[TASK-NNN
     • Edit matching lines: - [ ] [[TASK-NNN → - [x] [[TASK-NNN
     • Inline item sweep: collect remaining - [ ] free-text lines; use judgment to determine if the completing task accomplished them; Edit - [ ] → - [x] for those it clearly did; leave uncertain items unchecked
     • If ALL checklist items in the roadmap are now [x]: flip roadmap status: active → status: done; bump roadmap updated:; remove the roadmap's row from wiki/work/roadmaps/index.md; then archive the roadmap file:
       • git mv wiki/work/roadmaps/<file>.md wiki/work/roadmaps/archive/<file>.md
       • Append to wiki/work/roadmaps/archive/index.md: | [[ROADMAP-NNN]] | Title | done | YYYY-MM-DD |
     • Silent no-op if no roadmap references this task. Use Edit only (except git mv via Bash).
  6. Decision annotation — check the task body for a typed link implements::[[DEC-NNNN#DM]]:
     • If found: open wiki/work/decisions/DEC-NNNN-slug.md, find the "Source task(s):" line for this task, append — implemented YYYY-MM-DD to that line
     • Check wiki/work/tasks/ and wiki/work/tasks/archive/ for other tasks with status: todo|in-progress that also implements::[[DEC-NNNN#DM]]; if none remain, also append — decision fully implemented YYYY-MM-DD on a new line in the decision block
     • Decision inline checkbox sweep: collect remaining - [ ] lines in the ## D<N>. block; use judgment to decide which were accomplished; Edit accordingly
     • Use Read then Edit only — never sed
  7. Append log entry to wiki/log.md:

     ## [YYYY-MM-DD] uat | UAT-NNN passed · TASK-NNN done
     Archived UAT-NNN → uat/archive/ and TASK-NNN → tasks/archive/. [one sentence on what was verified]
     

  8. Report the task and UAT IDs and their new done/passed status, and the archive paths.

• Some failed (any [FAIL] or [FIXING] markers remain): Leave UAT file in wiki/work/uat/ with status: in-progress. Suggest next steps:

  To fix failures and re-test:  /uat-walk wiki/work/uat/UAT-NNN-slug.md
  To create fix tasks:          /task-add "Fix UAT failures in <feature>"
  

• Aborted: Leave UAT in wiki/work/uat/, note progress was saved in the file.

---

Important Rules

User Interaction

• Never skip the user prompt — every test requires explicit pass/fail from the user
• Mandatory verdict gate (see Step 4) — for batched tests, ask for all verdicts at once and stop until the user replies; for single (non-batched) tests, ask after each one and stop until the user replies. You may not advance to the next test/batch without an explicit verdict for every test in the current one.
• Never auto-pass or auto-fail — the user is the tester, the agent is the facilitator. This applies especially after a fix — a successful code fix does NOT mean the test passes. Always re-present and ask.
• Use inline prompts — do NOT use AskUserQuestion for verdicts. The user types their choice directly in the chat.
• API/CLI tests are auto-executed — never ask "Run / Manual / Skip?", just execute and show results
• Batch tests by type — API/CLI tests are batched (up to 5); UI tests are batched compactly (up to 3, one-liner format); manual tests are presented one at a time
• Flexible verdict input — accept "all pass", per-test lists, or selective overrides for batched verdicts
• Keep the test presentation clean and scannable

File Integrity

• Only modify status lines (- [ ] Pass → - [x] Pass, - [FAIL: ...], - [FIXING: ...], or - [SKIP: ...])
• Never rewrite or reformat the rest of the UAT file
• Preserve all existing metadata, headings, and structure
• [FIXING: ...] is always temporary — must resolve to [x] Pass, [FAIL: ...], [SKIP: ...], or [ ] Pass before moving on

Prerequisites

• Auto-verify first: for each unchecked prerequisite, attempt a deterministic check (one Bash call per item) before involving the user
• After checking, show verified ones (✅) and unverifiable/failed ones (❓) together in a single block
• Only ask the user to confirm the ones that couldn't be auto-verified or that failed
• If all prerequisites pass auto-verification, proceed without asking — note it in one line
• If a prerequisite fails, warn the user that subsequent tests may be affected but let them decide whether to continue

Progress Persistence

• Every verdict is written to the file immediately — if the user aborts or the session ends, progress is preserved
• On resuming a partially-completed walkthrough, it picks up from the first pending test

---

Begin Walkthrough

Now start the walkthrough:

1. Read the UAT file at: $ARGUMENTS
2. Parse all tests and count totals
3. Present the first pending prerequisite or test
4. Record the verdict
5. Repeat until done

Start now — read the UAT file and present the first test.