manual-test-script-author

Deep reference for manual-test-script-author SKILL.md. A full step-table script is overkill for some situations:

• A 5-minute production smoke after every deploy.
• An on-call's "is it broken?" first-pass verification.
• A periodic (weekly / monthly) compliance check.
• A bug-bash kickoff (give every participant the same checklist).

For these, a focused checklist wins: ~10-30 items, each one line, each with a clear pass/fail. The whole list fits on one screen / one printed page; the runner sweeps through it in 5-15 minutes. This format converts a regression suite (or test plan) into that checklist.

When to use this format

• After a deploy, the team needs a fast "did anything obviously break" sweep.
• On-call rotations want a "is the system broken?" template they can run before paging others.
• A bug-bash needs the same checklist for every participant so coverage is consistent.
• A compliance review needs a periodic verification record.

If the use case is "test a feature thoroughly before release," use the full step-table format from the SKILL.md body instead - expected results per step.

Step 1 - Pick scope

A checklist's value is its focus. Scope by one of:

Wider scope = lower run frequency = less repeated value.

Step 2 - Convert each test case to one-line form

Source TCs from the step-table scripts or the existing regression suite. Compress each to a single line with three slots:

[ ] [feature]: [action] → [observable outcome]

Examples:

[ ] **Login**: enter `qa-test-user@example.com` + password from vault item `QA / qa-test-user` → dashboard loads in <3s.
[ ] **Cart**: add `BOOK-001` → cart count badge shows "1".
[ ] **Promo code**: apply `WELCOME10` → subtotal drops by 10%.
[ ] **Checkout**: click `Place order` → confirmation page within 5s.
[ ] **Email**: order confirmation arrives within 5 min.

If a step needs 3+ lines to express, split into multiple checklist items OR move it back to the full step-table format - the checklist isn't the right artifact for that step.

Step 3 - Group by flow

A 30-item flat list is hard to scan. Group:

## Production smoke - release `v1.4.5`

**Tester:** ___________________  **Date:** ___________________  **Time:** ___________________
**Environment:** prod | staging   **Build SHA:** ___________________

### Auth flow

- [ ] **Login** (existing user): `qa-test-user@example.com` + password from vault item `QA / qa-test-user` → dashboard <3s
- [ ] **Logout**: click `Sign out` → redirect to `/login`
- [ ] **Password reset**: click `Forgot password` → email arrives within 5 min

### Cart + checkout flow

- [ ] **Add to cart**: SKU `BOOK-001` → cart count badge shows "1"
- [ ] **Cart page**: navigate to `/cart` → item visible with qty 1, $24.99
- [ ] **Promo code**: apply `WELCOME10` → subtotal drops to $22.49
- [ ] **Checkout**: complete checkout with the Stripe test-mode Visa → confirmation page

### Account flow

- [ ] **Profile update**: change email → save → reload → email persists
- [ ] **Order history**: view past orders → most recent test order present

### Sign-off

**Pass / fail / partial:**
**Defects raised:** (list IDs)
**Notes:**

The flow grouping doubles as a coverage check - empty groups mean the smoke doesn't cover that flow.

Step 4 - Time-box and document

A checklist that takes "as long as it takes" gets skipped. Set an explicit budget per group:

| Group               | Items | Budget |
|---------------------|------:|-------:|
| Auth flow            |    3  |  3 min |
| Cart + checkout flow |    4  |  6 min |
| Account flow         |    2  |  3 min |
| **Total**            |   9   | 12 min |

If the actual run exceeds the budget by >50%, the checklist is too long; trim to the highest-signal items.

Step 5 - Pair with a defect-raising flow

Same as the SKILL.md body's defect-raising step - checklist failures need a path to a logged defect:

### Defects raised this run

| # | Item                                          | Observed                            | Severity | Bug ID  |
|---|-----------------------------------------------|-------------------------------------|----------|---------|
| 1 | Promo code: apply WELCOME10                   | Subtotal stayed at $24.99           | high     | BUG-987 |

Step 6 - Versioning

The checklist evolves with the product. Keep it in docs/:

docs/checklists/
├── prod-smoke-v1.md
├── prod-smoke-v2.md          ← current
├── on-call-first-pass-v1.md
└── bug-bash-checkout-v1.md

Bumping the version when the items change (rather than mutating in place) preserves the historical record - useful for audit ("what did the smoke check on 2026-04-15?") and for retrospective on incidents that the smoke missed.

Output format

## Test execution checklists - `<feature/area>`

**Generated from:** `<source - TC suite / test plan / story>`
**Total items:** N
**Total wall-time budget:** M minutes
**Scope:** smoke | first-pass | full sweep | compliance

(per-checklist bodies follow per Step 3)

### Coverage notes

- Auth flow: N items covering login + logout + password reset
- Cart flow: N items covering add + view + checkout
- Areas NOT covered (intentional): admin panel (out of smoke scope),
  internationalized currencies (covered weekly via `prod-smoke-i18n.md`)

Anti-patterns

Limitations

• Subjective pass/fail. A one-line check ("dashboard loads in <3s") relies on tester judgment. For exact-value checks, use the full step-table format.
• Coverage gaps invisible. A 10-item smoke won't catch a regression in the 100 areas it doesn't cover. Pair with full regression runs at lower frequency.
• Tester fatigue. Same checklist run daily becomes mechanical; testers stop noticing the failures. Rotate checklists per week / per tester to keep attention fresh.
• No automation parity. A passing manual checklist doesn't imply an automated suite would pass; the checks are different by design.

References

• bug-bash-facilitator - consumes a checklist as the bug-bash kickoff template.
• smoke-suite-gate (qa-process) - automated equivalent for CI-runnable smoke.

Deep reference for manual-test-script-author SKILL.md. UAT scripts are written for stakeholders, not developers: the end user, subject-matter expert (SME), or solution owner runs the script in business language, and the success criterion is "this works for the business," not "no exceptions thrown." Sign-off is a contractual artifact - upon meeting the acceptance criteria the stakeholder signs off, confirming the product meets defined requirements (uat-wiki (opens in new window)).

When to use this format

• A release requires formal UAT - B2B contracts, regulated industries (finance, healthcare, gov), enterprise SaaS.
• A new feature needs business sign-off before launch.
• A vendor contract requires "customer acceptance" as the payment trigger.
• A migration / rebuild needs the customer to confirm "yes, this is what we wanted" before old system shutdown.

If the test is technical (verify HTTP 200, validate schema), use the step-table or Gherkin format from the SKILL.md body - the developer-facing formats.

Step 1 - Identify the user journey

Per uat-wiki (opens in new window):

"UAT should be executed against test scenarios representing user journeys rather than technical click-by-click steps."

A UAT script covers one user journey end-to-end, not a single button-click. The journey is what the business stakeholder agreed to in the contract / SOW / acceptance criteria.

Examples:

• "A new customer signs up, places a first order, and receives confirmation."
• "An existing customer updates their billing address and the invoice reflects the change next billing cycle."
• "An admin creates a new user, assigns roles, and the user can log in with the assigned permissions."

Per uat-wiki (opens in new window), select the "three most common or difficult tasks users will perform" - UAT depth, not breadth.

Step 2 - Format

# UAT-001 - New customer first-order flow

**Customer / Stakeholder:** ____________________
**Tester:** ____________________   **Date:** ____________________
**Environment:** UAT   **Build / Version:** v1.4.5

## Business context

This script verifies that a new prospective customer can complete
the full sign-up + first-order journey end-to-end, including
account creation, email confirmation, browsing the catalog, adding
items to cart, completing checkout, and receiving confirmation.

This corresponds to acceptance criterion **AC-1** in the SOW.

## Pre-conditions

- [ ] Test environment is at build `v1.4.5` (verified by tester).
- [ ] Tester has not previously created an account on this UAT
      environment.
- [ ] Test payment method is available: the Stripe test-mode Visa
      card for a successful payment, any expiry, any CVC.
- [ ] Tester has access to email inbox for `<email>@example.com`.

## Steps

| Step | Action                                                           | Expected outcome                                                        | Pass | Fail | Notes |
|------|------------------------------------------------------------------|-------------------------------------------------------------------------|:----:|:----:|-------|
| 1    | Open `https://uat.example.com/`. Click "Sign up".                  | Sign-up form appears.                                                    |      |      |       |
| 2    | Enter email `uat-001-<initials>@example.com`, set password.        | "Verify your email" prompt appears.                                      |      |      |       |
| 3    | Open the email inbox; click the verification link.                 | Browser opens to dashboard; greeting shows the user's name.              |      |      |       |
| 4    | Browse the catalog. Search for "BOOK-001".                         | Product page loads showing the item details and "Add to cart" button.   |      |      |       |
| 5    | Click "Add to cart". Click the cart icon.                          | Cart page shows "BOOK-001" qty 1, $24.99.                                 |      |      |       |
| 6    | Click "Checkout". Enter shipping address.                          | Order summary shows shipping cost; tax computed per address.             |      |      |       |
| 7    | Enter payment details (Stripe test Visa). Click "Place order".     | Confirmation page shows order ID; total matches step 6.                  |      |      |       |
| 8    | Open email inbox; verify confirmation email arrives within 5 min.  | Email shows order ID, items, total, expected delivery date.              |      |      |       |

## Acceptance criteria verification

| AC ID  | Description                                                | Verified in step | Pass / fail |
|--------|------------------------------------------------------------|------------------|:-----------:|
| AC-1.1 | New customer can sign up                                    | 1, 2, 3          |             |
| AC-1.2 | New customer can browse the catalog                         | 4                |             |
| AC-1.3 | New customer can add items to cart                          | 5                |             |
| AC-1.4 | New customer can complete checkout                          | 6, 7             |             |
| AC-1.5 | New customer receives order confirmation                    | 8                |             |

## Sign-off

**Tester:** ____________________  **Date:** ____________________

**Customer / Stakeholder:** ____________________  **Date:** ____________________

By signing, the stakeholder confirms that the system meets
acceptance criteria AC-1.1 through AC-1.5 as defined in the
Statement of Work, dated YYYY-MM-DD.

## Defects raised

| Bug ID | Step | Severity | Description |
|--------|------|----------|-------------|
|        |      |          |             |

Step 3 - Business language, not implementation

UAT scripts are read by stakeholders who don't speak HTTP / DB / React. Translate:

The script is about outcomes, not mechanisms.

Step 4 - Three-tasks rule

Per uat-wiki (opens in new window): "the three most common or difficult tasks users will perform" - UAT covers depth, not breadth.

A UAT round shouldn't have 50 scripts. The pattern:

• 5-10 scripts covering the three most common user journeys.
• 2-5 scripts covering the two or three most difficult tasks (the ones that go wrong most often in the team's history).

If the contract has 30 acceptance criteria, group them into ~10 journeys; one script per journey.

Step 5 - Run the round, log defects, re-test

Execute each script with the stakeholder. For every failed step, log a defect in the "Defects raised" table (Step 2 format) with its step and severity. Verify: every row in the acceptance-criteria table must read pass before sign-off; if any AC fails, hand the defects to the team, fix them, and re-run the affected scripts. Repeat until all acceptance criteria pass - do not proceed to sign-off with an open failing AC.

Step 6 - Sign-off as artifact

The signed UAT scripts go into the customer record:

• Hard-copy file (paper-signed for legal records).
• Soft-copy in the team's contract management system.
• PR comment in the team's repo (referencing the signed PDF).

The sign-off date triggers the contractual milestone (payment, go-live authorization, vendor approval).

Anti-patterns

Limitations

• Stakeholder availability. UAT requires the customer's time; scheduling is the rate-limiter.
• Soft acceptance. Stakeholders may sign off without thoroughly testing; the script's structure helps but doesn't enforce.
• No automation parity. UAT explicitly tests the user experience; automated tests of the same steps don't substitute.
• Per-customer customization. B2B UAT often requires customer-specific scripts (their data, their workflows). Scale by tenancy, not by template.

References

• uat-wiki (opens in new window) - User acceptance testing definition: who runs it (end user / SME / solution owner), purpose (sign-off as contractual artifact), format (user journeys, not technical click-steps), three-most-common-or-difficult-tasks rule.
• gherkin-from-stories (in the qa-bdd plugin) - upstream: emits the ACs this format turns into UAT scripts.