create-manual-test-instructions v1.8A

Immutable. This exact content never changes and is served at /api/v1/blob/19d4f043fe3e9522.

---
name: create-manual-test-instructions
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.8"
---

# Create manual test instructions

## 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. 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** and, for a branch or PR, the
target and the source state (tip or working tree) you diffed.