UAT-cycle

UAT-cycle

Executing UAT cycle: $ARGUMENTS

Phase 1: Select Test Case

If a test case ID was provided (e.g., UAT-001):

1. Read docs/testing/UAT_COVERAGE.md
2. Find the test case by ID
3. Present it to the user:
   • Test Case ID: UAT-###
   • Title: [title]
   • Covers: [backlog story IDs or feature area]
   • Prerequisites: [what's needed]
   • Steps: [numbered steps]
   • Acceptance Criteria: [checklist]
4. Ask: "Ready to start testing? Are all prerequisites met?"

If a description was provided instead of an ID:

1. Read docs/testing/UAT_COVERAGE.md
2. Find the best matching test case(s)
3. If ambiguous, present options for the user to choose
4. Once selected, present as above

If no argument was provided:

1. Read docs/testing/UAT_COVERAGE.md
2. Show the status summary table
3. List all test cases with status "Not Tested" (prioritized) or "Fail" (for retesting)
4. Ask the user to select which test case to execute

Phase 2: Execute Test

Persona Context Loading

If the test case's parent story has a Personas: field (not "internal"), load the referenced persona(s) from docs/context/personas.md. When persona context is available:

• Frame test guidance from the persona's perspective — use their context (device, proficiency, constraints) to inform how the test should be performed
• Present steps with persona awareness — e.g., "As [Name] ([Role]), try to [step]. Given their [constraint], watch for [specific friction point]."
• Evaluate results against the persona's EVALUATES BY questions in addition to the acceptance criteria
• Flag FAILURE LOOKS LIKE matches — if a test result resembles the persona's failure scenario, escalate severity

Skip when: No Personas: field on the story, personas.md doesn't exist, or the test case is purely technical (API contract, data migration, etc.).

Test Execution

The user performs the test steps manually (or with automation tooling). Claude assists by:

1. Ensuring prerequisites: Check that required services, data, or environments are available
   • If prerequisites aren't met, help the user set them up
2. Guiding through steps: Present steps one at a time or all at once (user preference). If persona context was loaded, annotate steps with persona perspective where relevant.
3. Collecting results: After the user completes testing, ask for results on each acceptance criterion:
   • Pass / Fail / Blocked / Not Applicable
   • Any observations, screenshots, or feedback per criterion
   • If persona context loaded: "From [persona name]'s perspective, did this meet their expectations?"
4. Recording findings: For each failing criterion, ask:
   • What happened vs. what was expected?
   • Severity: Critical / Major / Minor / Cosmetic
   • Any error messages or unexpected behavior?
   • If persona context loaded: note which persona is most affected

Phase 3: Process Findings

For each finding (failing acceptance criterion), classify and act:

For each finding:

Bug (Critical)

1. Investigate: Find the root cause in code
2. Test first: Write a failing test capturing the bug
3. Fix: Minimal code change
4. Verify: Run the project's test command (from CLAUDE.md)
5. Ask user to re-verify the specific acceptance criterion
6. Commit: fix(scope): description

Bug (Minor)

1. Identify the issue in code
2. Fix with minimal change
3. Add test if regression-prone
4. Run the project's test command
5. Commit: fix(scope): description

Gap

1. Document clearly
2. Write a user story (INVEST format) and add to the appropriate backlog file in docs/reference/backlog/
3. Do NOT implement — scope control
4. Report what was logged

Enhancement

1. Evaluate scope: Trivial (< 10 lines) → ask user if should fix now
2. Larger → log to backlog
3. Act accordingly

Known Issue

1. Confirm the issue matches the known issue description
2. Note it in the test results (no fix needed, already tracked)

Phase 4: Update UAT Coverage

After all findings are processed:

1. Update docs/testing/UAT_COVERAGE.md:

   • Set the test case Status to: Pass (all criteria met) / Fail (any criteria failed and unfixed) / Pass (if all failures were fixed during this cycle)
   • Set Tested On to today's date
   • Add Findings notes summarizing what was found and done
   • Update the Dashboard table at the top of the file
   • Check/uncheck the acceptance criteria checkboxes based on results
   • Append a row to the test case's #### Results table: | [status emoji] [status] | [today's date] | [tester] | [build via git rev-parse --short HEAD] | [one-line summary] | Never delete existing rows — the Results table is an append-only execution log.

2. Update acceptance criteria checkboxes:

   • [x] for criteria that passed
   • [ ] for criteria that still fail (with a note explaining why)

Phase 5: Close Cycle

Run verification

1. Run the project's test command (from CLAUDE.md) to confirm all automated tests still pass

Commit changes

If any code was changed during this cycle:

1. Stage relevant files
2. Commit with: test(UAT): <test-case-id> — <summary of findings>
3. Include fixes in the commit or as separate commits with proper conventional format

Completion Report

### UAT Cycle Complete

**Test Case:** UAT-### — [title]
**Result:** Pass / Fail / Partial
**Acceptance Criteria:** [x/y] passed
**Findings:**
- [summary of each finding and action taken]

**Files Modified:** [list]
**Commits:** [hash(es) and message(s)]
**Backlog Items Created:** [story IDs if any gaps were logged]

**Next:** Select another test case (`/UAT-cycle <id>`) or finish testing session.

Rules

• NEVER skip presenting the test case to the user first
• NEVER auto-pass acceptance criteria — only the user can confirm pass/fail
• ALWAYS update the UAT coverage file after each cycle
• ALWAYS commit code changes with proper conventional format
• Log gaps to the appropriate backlog file, not as inline TODOs
• Follow coding standards in docs/reference/CODING_STANDARDS.md