create-manual-test-instructions · diff

v1.7 to v1.8

45 added, 13 removed. Audit A to A.

---
name: create-manual-test-instructions
- description: Turn a ticket or requirements document into a concise QA manual-test file a non-author can follow. Invoke manually only.
+ description: Turn a ticket, requirements document or code change (branch, PR, commit range, diff) into a concise QA manual-test file a non-author can follow. Invoke manually only.
context: fork
license: MIT
metadata:
- version: "1.7"
+ version: "1.8"
---
# Create manual test instructions
- Read the input ticket or requirements document and, where needed for accurate navigation, the
- code it cites and the design frames or screenshots it links when they are on disk. Write the
- manual-test file in the **same directory**, naming it by replacing `.REQUIREMENTS` or `.TICKET`
- with `.MANUAL-TEST` (e.g. `FOO.REQUIREMENTS.md` → `FOO.MANUAL-TEST.md`); if the input follows
- neither convention, append `.MANUAL-TEST` before `.md`. If there is no file (pasted text), follow
- the project's/user's convention for where plans live (default: `.agents/plans/`), derive a
- kebab-case `<slug>` from the content, and write `<slug>/<slug>.MANUAL-TEST.md` there. An existing
- manual-test file of that name is replaced; the final message says so. Running forked, you can't
- ask mid-run: flag any guessed location or slug in the final message for the user to verify.
+ ## Resolve the input
+ - **Ticket or requirements document** (file or pasted text) — the only source: the checks follow
+ it, and no code change is looked up.
+ - **Code change** — a branch, PR URL, commit range, pasted diff or patch file, or nothing (the
+ current branch). A commit range is diffed between its own ends. A branch or PR: `git fetch` the
+ remotes, then diff from the merge base `<base>` with the target — a PR's base from its
+ metadata, else the default branch of the `upstream` remote when one exists, else of `origin`,
+ via `git ls-remote --symref <remote> HEAD`; that failing, the sole existing candidate among
+ `main`, `master`, `develop`/`development`, preferring `upstream`'s remote-tracking ref, then
+ `origin`'s, then the local branch. `git diff <base> <source>` for a tip; a checked-out source
+ is reviewed as its working tree: `git diff <base>` plus the untracked files
+ (`git ls-files --others --exclude-standard`), read whole. Read the commit subjects and the PR
+ title and description too. Then resolve the task's planning home — its `<id>-<slug>/` directory
+ (no ticket → no id) or flat `<id>-<slug>.*` files in the project's planning directory, id and
+ slug from the branch name or PR — and read the ticket and requirements there when present for
+ the intent, the "before" and the edge cases; the checks still follow the code. No merge base →
+ `git fetch --unshallow` and retry. Running forked, you can't ask mid-run: an ambiguous target, a
+ failed fetch, still no merge base or an empty diff → write nothing and say in the final message
+ what to pass on the next run; never guess a target.
+
+ Where needed for accurate navigation, also read the code the input cites and the design frames or
+ screenshots it links when they are on disk.
+
+ ## Write the file
+
+ Next to an input ticket or requirements file, naming it by replacing `.REQUIREMENTS` or `.TICKET`
+ with `.MANUAL-TEST` (`FOO.REQUIREMENTS.md` → `FOO.MANUAL-TEST.md`); neither convention → append
+ `.MANUAL-TEST` before `.md`. A code change with a planning home → `<id>-<slug>.MANUAL-TEST.md`
+ beside the task's other artifacts. Otherwise (pasted text, a diff or patch file, a branch without
+ artifacts) follow the project's/user's convention for where plans live (default: `.agents/plans/`)
+ and write `<id>-<slug>/<id>-<slug>.MANUAL-TEST.md` there, id and slug from the branch name or PR,
+ else a kebab-case slug from the content. An existing manual-test file of that name is replaced;
+ the final message says so. Flag any guessed location or slug in the final message for the user to
+ verify.
+
The file must be followable by someone **unfamiliar with the ticket** — short but complete. Four
parts:
1. **What changed** — 1–2 sentences: the feature and the user-visible difference.
2. **How to get there** — concrete navigation to the affected area (entry point, page/screen name,
any prerequisite state).
3. **Before vs after** — how the area behaved before, how it should behave now.
4. **What to verify** — checklist of behaviors to confirm, including edge cases (empty values,
multiple items, boundaries) where relevant. A behaviour resting on an Open question of the
input goes under a closing **Not settled yet** line, never as a plain check: on a non-blocking
question, with its tentative answer; on a blocking one, listed as undecided, naming who decides
- when the input names them, with no expected value — never invented.
+ when the input names them, with no expected value — never invented. Each point where a code
+ change differs from its ticket — built but never asked for, or asked for but not built — goes
+ under a closing **Differs from the ticket** line, with nothing invented for the missing side.
+ A change with nothing a person can test by hand (a refactor, a dependency bump, a backend change
+ with no visible effect) still gets the file: part 1 says why, the other parts stay empty.
+
Before writing, actually invoke [explain-in-simple-language](../explain-in-simple-language/SKILL.md)
and follow it — reciting its rules from memory does not count. Not installed: plain words, one idea
per sentence, and nothing named only by a stand-in the reader hasn't seen.
Do not modify any source files; the only file you write is the manual-test document.
- When done, state the manual-test file's **project-relative path**.
+ When done, state the manual-test file's **project-relative path** and, for a branch or PR, the
+ target and the source state (tip or working tree) you diffed.