user-acceptance

Original：🇺🇸 English

Translated

Use when finishing a ticket or pull request and the user asks to validate, demo, or sign off on delivered behavior, including non-user-facing changes. Triggers include "UAT", "verify", "walk me through", "show what changed", "can we merge?", "sign off", "acceptance test", "demo this", "ready to merge", "validate the changes", "show me it works", and similar phrases indicating a need for an acceptance walkthrough or demonstration before merge.

2installs

Sourcegannonh/skills

Added on2026-03-04

NPX Install

npx skill4agent add gannonh/skills user-acceptance

SKILL.md Content

View Translation Comparison →

Running User Acceptance Walkthroughs

Overview

Acceptance at delivery time should be experiential, not just a test summary. Primary goal: help the human directly see and feel what changed before merge. If work is not user-facing, run and show executable proof with user-impact translation. For user-facing work, run a live end-to-end demo using the appropriate automation tool for the platform. Then give the user instructions for running it themselves.

When to Use

End of PR/ticket prompts: "UAT", "verify", "walk me through", "show what changed", "can we merge?"
Sign-off requests where confidence requires direct observation, not only CI output
Mixed work (UI + backend/infrastructure) that needs both walkthrough and proof

Do not use for mid-implementation debugging or code-quality review without acceptance intent.

Decision Flow

dot

digraph uat_flow {
  "End-of-ticket or PR acceptance?" [shape=diamond];
  "Any user-facing behavior changed?" [shape=diamond];
  "Detect platform" [shape=diamond];
  "Can agent execute proof locally?" [shape=diamond];
  "Run web/Electron demo" [shape=box];
  "Run iOS/macOS demo" [shape=box];
  "Run CLI/API demo" [shape=box];
  "Provide reproducible proof plan + user run steps" [shape=box];

  "End-of-ticket or PR acceptance?" -> "Any user-facing behavior changed?" [label="yes"];
  "Any user-facing behavior changed?" -> "Detect platform" [label="yes"];
  "Any user-facing behavior changed?" -> "Can agent execute proof locally?" [label="no"];
  "Detect platform" -> "Run web/Electron demo" [label="web or Electron"];
  "Detect platform" -> "Run iOS/macOS demo" [label="iOS/macOS native"];
  "Detect platform" -> "Run CLI/API demo" [label="CLI/API/backend"];
  "Can agent execute proof locally?" -> "Run CLI/API demo" [label="yes"];
  "Can agent execute proof locally?" -> "Provide reproducible proof plan + user run steps" [label="no"];
}

Step-by-Step Workflow

1. Identify scope, mode, and platform

Confirm what behavior is being accepted.
Declare
```
Mode
```
:
```
user-facing
```
,
```
non-user-facing
```
, or
```
mixed
```
.
For user-facing work, detect
```
Platform
```
to select the right demo tool:

Signal	Platform	Playbook
Xcode project, `.xcodeproj` , `.swift` files, iOS simulator	iOS/macOS native	`./references/ios-demo-playbook.md`
Web app, `package.json` with dev server, browser-based UI	Web	`./references/web-demo-playbook.md`
Electron app, `electron` in dependencies	Electron	`./references/web-demo-playbook.md` (Electron section)
CLI tool, API endpoint, backend service, infrastructure	CLI/API	`./references/cli-api-demo-playbook.md`

If the platform is ambiguous, ask the user.

2. Define acceptance slices

Break validation into small slices (2-5), each with clear pass/fail criteria.

How to derive slices:

Start from the ticket's acceptance criteria if they exist
Otherwise, map each user-visible behavior change to a slice
For non-user-facing work, map each functional change to a demonstrable proof
Each slice should be independently verifiable — avoid slices that only pass if run in sequence

3. Execute validation

Follow the appropriate playbook:

User-facing (web/Electron):
```
./references/web-demo-playbook.md
```
User-facing (iOS/macOS):
```
./references/ios-demo-playbook.md
```
Non-user-facing or CLI/API:
```
./references/cli-api-demo-playbook.md
```
Mixed: run user-facing demo first, then technical proof tied to the same outcome.

4. Capture evidence

Save screenshots/video for user-facing slices.
Save exact commands and key output lines for technical slices.

5. Report results to the user

Start with overview and scope bullets.
List each slice with explicit
```
Pass
```
/
```
Fail
```
.
Provide instructions to the user for running the same validation themselves.
End with
```
Recommendation
```
:
```
GO
```
,
```
GO with follow-ups
```
, or
```
NO-GO
```
.

6. Update ticket (required on success)

If recommendation is

GO

GO with follow-ups

, post a ticket comment in the project system of record (check CLAUDE.md or project config; common systems: Linear, Jira, GitHub Issues) with:

UAT verdict (
```
GO
```
/
```
GO with follow-ups
```
)
Scope validated (2-5 bullets)
Mode and platform used
Slice-by-slice pass/fail summary
Evidence links or file paths (screenshots, videos, logs)
Commands run (for non-user-facing or mixed technical slices)
Any follow-ups or residual risks

If no ticket is known, ask for the ticket ID before closing UAT. Do not mark acceptance complete until this ticket update is posted.

Quick Reference

Mode	First step	Evidence required	Done when
user-facing	Run platform-appropriate demo (slice 1)	Demo trace + screenshots/video + observed UI	User confirms pass/fail for all scenarios
non-user-facing	Run proof command(s)	Command output + impact translation	Reproducible evidence reviewed
mixed	User-facing demo first, then technical proof	Both demo evidence and technical proof	Both layers accepted

Common Mistakes

Dumping a static checklist with no interaction
Reporting only test counts with no demonstration
Skipping a live demo for user-facing changes
Skipping non-UI demo because there is no frontend change
Declaring merge readiness before collecting explicit pass/fail signals
Using the wrong demo tool for the platform (e.g., agent-browser for an iOS app)

Rationalization Table

Excuse	Reality
"No UI changes, so UAT is just unit tests."	Non-user-facing work still needs demonstrable proof and user-impact explanation.
"We are in a rush, give a fast merge checklist."	Time pressure increases need for clear GO/NO-GO evidence.
"I already summarized everything; that is enough."	Summaries do not replace user experience or executable demonstration.
"User can test later after merge."	Acceptance belongs before merge unless explicitly deferred by user.
"Tests pass, so it works."	Tests prove code correctness. Acceptance proves the right thing was built.

Red Flags - Stop and Correct

You are about to send only a summary/checklist.
You cannot point to any observed behavior or executed proof.
You are treating CI green status as equivalent to acceptance.
You are asking for merge without an explicit acceptance signal.
You skipped platform detection and defaulted to the wrong demo tool.