write-test-scenarios

name	write-test-scenarios
description	Generate manual test scenarios (UC/TC) from the spec file after implementation — use cases and step-by-step test cases for human testers to verify the feature by hand. Output saved to .ai/tasks/<name>-manual-tests.md.

Write Test Scenarios

Generate manual test documentation (UC + TC) based on the written spec, so the user can verify the feature by hand after implementation is complete.

Output: file .ai/tasks/<task-name>-manual-tests.md

---

Run

Step 1 — Read inputs

Read: .ai/tasks/<task-name>.md    ← get Goal + Test plan + Constraints
Read: .ai/context/domain-glossary.md  ← use correct domain terminology

List all items in ## Test plan — this is the list of UCs to write.

Step 2 — Identify Use Cases

Group test plan items into UCs by user flow. One UC = one user journey with a clear start and end.

Example:

Test plan items:
- happy path: password reset succeeds
- edge case: token expired
- edge case: token reused
- no regression: login still works normally

→ UC-01: Successful password reset
→ UC-02: Handle invalid token
→ UC-03: Login flow unaffected (regression)

Step 3 — Write test file

Create .ai/tasks/<task-name>-manual-tests.md using the following format:

# Manual Tests: <task-name>

**Feature:** <short description from spec Goal>
**Tester:** ___________
**Test date:** ___________
**Environment:** ___________   (staging / local / production)

---

## UC-01: <use case name>

> <1-2 sentence description of the use case — who does what, and why>

**Preconditions:**
- <condition that must be true before starting the test>
- ...

---

### TC-01-01: <specific test case name>

| | |
|---|---|
| **Priority** | High / Medium / Low |
| **Type** | Happy path / Edge case / Regression / Error handling |

**Steps:**
1. <specific step — detailed enough for someone without code knowledge to follow>
2. ...
3. ...

**Expected result:**
- <what must happen — specific and observable>
- ...

**Actual result:** ___________

**Pass / Fail:** ⬜ Pass  ⬜ Fail

**Notes:** ___________

---

### TC-01-02: <next test case in the same UC>
...

---

## UC-02: ...

Step 4 — Rules for writing good TCs

Steps must be specific enough for someone without code knowledge to follow:

# Good
1. Open browser, navigate to http://localhost:3000/forgot-password
2. Enter "[e-mail]" in the "Email" field
3. Click the "Send password reset link" button
4. Check the inbox of [e-mail]

# Bad
1. Call the reset password API
2. Check the result

Expected result must be observable:

# Good
- Page shows message "Email sent. Please check your inbox."
- Email arrives within 60 seconds with subject "Reset your password"
- Link in email matches the format https://.../reset?token=...

# Bad
- System processes correctly
- No errors

Preconditions must be clear:

• What data must exist (user account, order, ...)
• Required system state (email server running, feature flag enabled, ...)
• What permissions the tester needs

Step 5 — Ensure coverage

Verify each item in ## Test plan of the spec has at least 1 TC:

[ ] happy path → TC-XX-XX
[ ] edge case 1 → TC-XX-XX
[ ] no regression → TC-XX-XX (regression)

If any Test plan item has no TC → add it before saving.

Step 6 — Report

After creating the file, report:

Created: .ai/tasks/<task-name>-manual-tests.md
- X use cases
- Y test cases (Z high priority)

---

Quick format guide by TC type

Happy path: Primary actor, normal conditions, straight-through flow from start to finish.

Edge case: Boundary inputs (empty, too long, special characters), abnormal states (expired, already used, duplicate), concurrent actions.

Error handling: System responds correctly when an error occurs — clear message, no crash, no sensitive information leaked.

Regression: Existing flows not directly related to the new feature — must verify they still work normally.