generate-uat-tests
Generate a structured set of human-executable UAT test cases from SPEAKMAN.AI Phase 1/2 outputs and the implemented codebase, traced back to use cases and business requirements. Use when the user want
SKILL.md.claude/skills/generate-uat-tests/SKILL.md
GitHubgenerate-uat-tests — Human UAT Test Case Generator
You generate a structured set of human-executable UAT test cases from Phase 1/2 SPEAKMAN.AI outputs and the implemented codebase. The output is a Markdown document a QA tester works through manually in a browser — not automated tests.
Every test case maps to a UC-ID from the Phase 2 use case catalog, which maps back to a business requirement from Phase 1. This closes the traceability chain:
Business outcome → Requirement → Use Case → UAT test → Pass/Fail → Functionality Score
The completed test results feed directly into /promote-environment 3 (QA→PROD gate), which
reads this file to compute the functionality score.
Step 0 — Collect Inputs
Ask the user:
"Provide the following:
- Phase 1 SAD output directory (contains raw/business_context_clarifier.txt and raw/business_analyst.txt) — or press Enter to skip
- Phase 2 requirements output directory (contains raw/use_case_catalog.txt, raw/api_schema.txt, etc.) — required
- Project root (the implemented codebase) — press Enter to skip if not available
- Output path for the UAT document (e.g. D:\git\my-project\uat) — will be created if absent
- Application base URL for test steps (e.g. http://localhost:5174) — default: http://localhost:5174"
Store:
- PHASE1_DIR: path or null
- PHASE2_DIR: path (required — stop if absent)
- PROJECT_ROOT: path or null
- OUTPUT_DIR: absolute path
- APP_URL: base URL testers will use (default
http://localhost:5174)
Step 1 — Load Contracts
Read everything before generating any test cases. Do not guess at content.
1a — Phase 1 (if PHASE1_DIR provided)
Read from {PHASE1_DIR}/raw/ — skip any file that is absent:
| File | Variable | Contains |
|---|---|---|
business_context_clarifier.txt |
P1_CONTEXT | Business goals, intended outcomes, KPIs, success criteria, in-scope/out-of-scope |
business_analyst.txt |
P1_REQUIREMENTS | Requirement IDs (FR-XX, NFR-XX) with descriptions and acceptance criteria |
If PHASE1_DIR is null, set P1_CONTEXT = null and P1_REQUIREMENTS = null. Note that requirement traceability will be limited to UC-IDs only — the Scope Creep detection and business outcome sections will be omitted.
1b — Phase 2 (required)
Read from {PHASE2_DIR}/raw/:
| File | Variable | Contains | Required? |
|---|---|---|---|
use_case_catalog.txt |
USE_CASES | UC-IDs, actors, Gherkin Given/When/Then, req_refs | Required — stop if absent |
api_schema.txt |
API_SCHEMA | All endpoints, request/response shapes, field types | Required |
business_analyst.txt |
P2_REQUIREMENTS | Requirement IDs and descriptions (Phase 2 may have refined them) | Optional |
field_definitions.txt |
FIELD_DEFS | Field constraints — valid formats, max lengths, allowed values | Optional |
Use P2_REQUIREMENTS if present, otherwise P1_REQUIREMENTS. If both are present, P2_REQUIREMENTS takes precedence (it is the reviewed version).
1c — Codebase scan (if PROJECT_ROOT provided)
Read source files to determine:
- Which routes are implemented (compare against API_SCHEMA for gap detection)
- What features exist beyond the use case catalog (scope creep candidates)
- Confirm the application base URL / port
If PROJECT_ROOT is null, set SCOPE_DELTA = null. Note the omission in the document.
Step 2 — Build the Requirements Index
From the requirements source (P2_REQUIREMENTS or P1_REQUIREMENTS), extract REQ_INDEX:
[
{ "id": "FR-01", "description": "Users can log in with username and password" },
{ "id": "NFR-03", "description": "All endpoints require authentication except /health" },
...
]
If no requirements source is available, derive a minimal index from the req_refs fields in
USE_CASES — treat the UC title as a stand-in description.
Step 3 — Generate Test Cases
For each UC-ID in USE_CASES, generate one or more test cases. Work through the entire use case catalog — do not skip any UC-ID.
One UC → one or more test cases:
- Always generate a happy-path test case (the main success scenario)
- If the UC contains explicit unhappy-path Gherkin scenarios (error cases, rejected inputs, access-denied flows), generate one additional test case per scenario
- Mark each test case
type: Happy pathortype: Negative
Test case ID sequence: TC-001, TC-002, ... across all test cases regardless of UC grouping.
For each test case, populate all fields:
| Field | Source / Rule |
|---|---|
test_id |
TC-{n:03d} — sequential across the whole document |
uc_id |
UC-ID from use case catalog |
req_ref |
req_refs from the UC entry (comma-separated); cross-reference REQ_INDEX for descriptions |
actor |
actor from the UC |
feature |
Short name of the use case (2–5 words, title case) |
scenario |
Gherkin scenario title, or "Happy path" / "Negative — {reason}" if no title |
type |
Happy path / Negative |
preconditions |
Derived from Given clauses + any required system state |
steps |
Numbered, human-executable actions (see rules below) |
expected_result |
Observable outcome (see rules below) |
actual_result |
(blank — tester fills in) |
status |
(blank — tester marks PASS / FAIL / BLOCKED) |
tester |
(blank — tester initials or name) |
date |
(blank) |
notes |
(blank — for deviations, screenshots, observations) |
Step writing rules
Steps must be executable by a non-developer with no access to the database or server logs.
- Write steps as imperative actions: "Click", "Enter", "Navigate to", "Select", "Wait for"
- Name UI elements as they appear in the application (button labels, form field labels, tab names)
- Include all setup: log in, navigate, create prerequisite records
- State data values verbatim:
Name: "Test Client A",IP Ranges: "192.168.1.1/32" - For API-only interactions with no UI control, write a curl command the tester can paste into a terminal
- Separate setup, action, and observation into distinct numbered steps — do not combine them
- If a later test case depends on data created by an earlier one, say so explicitly in Pre-conditions
Expected result rules
- Must be observable and unambiguous: "A green success banner appears with the text 'Scope saved'" — not "scope is saved"
- For list views: "A new row appears in the table with name 'Test Client A' and status 'PENDING'"
- For error cases: state the exact error message visible on screen, or the HTTP status code and body if testing via curl
- Reference field names and labels as they appear in the UI, not JSON field names
- Do not say "it works" or "the action succeeds" — describe what the tester sees
Step 4 — Scope Delta Analysis
Compare the API_SCHEMA routes against the UC-IDs to detect mismatches.
Untraced features (in codebase/API schema but not mapped to any UC-ID):
- Identify API endpoints or UI controls that cannot be traced to a UC-ID
- These are scope creep candidates — they were built but not in the requirements
Unimplemented use cases (UC-IDs in catalog but no corresponding route):
- Identify UC-IDs where no API endpoint implements the described scenario
- These are potential gaps in the implementation
Build SCOPE_DELTA:
{
"untraced_features": [
{ "endpoint": "POST /api/engagements/{id}/pipeline/gate4/complete",
"note": "No UC-ID in catalog — possible undocumented gate completion flow" }
],
"unimplemented_uc_ids": [
{ "uc_id": "UC-12", "title": "Export report as PDF", "note": "No route found in codebase" }
]
}
If PROJECT_ROOT was null, set SCOPE_DELTA = null and note codebase was not scanned.
Step 5 — Write UAT Document
Create {OUTPUT_DIR}/uat_test_cases.md. Write the full document using the Write tool — do not
produce a partial stub.
Document structure:
# UAT Test Cases
| | |
|---|---|
| Generated | {today ISO date} |
| Phase 2 source | {PHASE2_DIR} |
| Phase 1 source | {PHASE1_DIR or "not provided"} |
| Application URL | {APP_URL} |
| Total test cases | {count} |
| UC-IDs covered | {covered} / {total} |
| Happy path | {count} |
| Negative | {count} |
---
## Business Outcomes (Traceability Anchor)
{Only include this section if P1_CONTEXT is available.}
The following business outcomes were stated in the Phase 1 brief. Each is linked to the use
cases (and therefore test cases) that provide evidence it was achieved.
| Outcome | UC-IDs | Test Cases |
|---|---|---|
| {outcome from P1_CONTEXT} | UC-01, UC-03 | TC-001, TC-004 |
| ... | | |
---
## Scope Delta
### Features not traced to a use case
{List from SCOPE_DELTA.untraced_features, or "None identified" or "Codebase not scanned — provide PROJECT_ROOT to enable this check"}
### Use cases with no implementation found
{List from SCOPE_DELTA.unimplemented_uc_ids, or "None identified" or "Codebase not scanned"}
---
## Test Execution Tracker
| Total | Not Run | Pass | Fail | Blocked |
|---|---|---|---|---|
| {total} | {total} | — | — | — |
_Update this table as tests are executed._
---
## Test Cases
{For each UC-ID, one ### heading. All test cases for that UC appear under it.}
### {Feature Name} — {UC-ID}
**Requirement:** {req_ref} — {requirement description from REQ_INDEX}
**Actor:** {actor}
---
#### TC-001 · Happy path — {scenario title}
**Type:** Happy path
**Pre-conditions**
- {pre-condition 1}
- {pre-condition 2}
**Steps**
| # | Action | Expected Result |
|---|---|---|
| 1 | Navigate to {APP_URL} | Login page is displayed |
| 2 | Enter Username: `lead_analyst`, Password: `ChangeMe123!`, click **Log In** | Redirected to the Engagements list page |
| 3 | {action} | {expected observable result} |
**Execution Record**
| Actual Result | Status | Tester | Date | Notes |
|---|---|---|---|---|
| | | | | |
---
#### TC-002 · Negative — {scenario title}
{same structure}
---
{next UC-ID heading}
Step 6 — Report
UAT Test Cases — {PHASE2_DIR basename}
────────────────────────────────────────
Output : {OUTPUT_DIR}/uat_test_cases.md
Test cases : {total}
UC-IDs covered : {covered} / {total} ({pct}%)
Happy path : {count}
Negative : {count}
Untraced features : {count} (scope creep candidates)
Unimplemented UCs : {count}
Then say:
"Open
uat_test_cases.mdand work through each test case in the application at {APP_URL}. For each test, fill in the Actual Result, Status (PASS / FAIL / BLOCKED), your initials in Tester, and today's date. Update the Test Execution Tracker table at the top as you go.When all tests are executed, run
/promote-environment 3— the gate will read this file to compute the functionality score before deciding whether to allow PROD promotion."
Rules
- Never invent use cases. Every test case maps to a UC-ID from the Phase 2 catalog. Features observed in the codebase that have no UC-ID go to SCOPE_DELTA, not to test cases.
- Steps must be human-executable. No Python, no database queries, no internal calls a UI tester cannot make. If the only path is via API, write a curl command.
- Expected results must be observable. What the tester sees, reads, or can copy. Not what the server does internally.
- Cover every UC-ID. A use case with no test case is a gap. If a UC cannot be tested because it has no UI and no documented API endpoint, note it as BLOCKED in SCOPE_DELTA.
- One happy path per UC minimum. Negative tests add depth; they do not substitute for the happy path.
- Do not modify Phase 2 contracts. Read only. The UAT document is derived from contracts, not a revision of them.
- Write the complete document. Do not produce a stub or a subset. Every UC-ID gets its test cases in the output file.