unlearndev Manual QA checklist from a diff
Produce a short checklist a human can click through in the deployed app to confirm this change works. The reader is a person with a browser and a test account — not a developer reading code. Every step must be something they can do and observe through the UI (or, rarely, an email inbox / API client if the change only surfaces there).
This is not a regression suite and not a code review. Cover only what this diff changed, plus the one or two adjacent flows most likely to break as a side effect. If the checklist grows past ~10 steps, it's too broad — cut it back to what the change actually touched.
1. Get the diff
Default to comparing the current branch against main; respect any base, commit range,
or PR the user names instead.
git fetch origin
git diff origin/main...HEAD --stat # overview
git diff origin/main...HEAD # read the whole diff
Use ... (merge-base) so you see only what this branch adds. Where the diff alone is
ambiguous, open the touched files — you need to understand the user-visible behaviour,
not just the lines that moved.
2. Translate code changes into user-visible behaviour
For each change, ask: "what would a user see or do differently because of this?" That question decides what goes on the checklist.
- Controllers / routes / pages — the pages and actions to exercise. New route → visit it; changed store/update logic → submit the form and check the result.
- Validation & authorization — the failure paths are QA steps too: submit the invalid input and confirm the inline error; try the action as a user who shouldn't be allowed and confirm it's blocked.
- Frontend components — the interactions to click: toggles, modals, optimistic updates, empty states, flash messages.
- Feature flags — if behaviour is gated (e.g. Pennant), include checking both sides: flag on shows the feature, flag off hides it cleanly. Say how to identify a flagged account if the diff makes that clear.
- Emails / notifications / jobs — trigger the action, then check the observable result (email arrives, notification appears). Skip anything with no observable surface.
- Migrations / data changes — only if they change what users see (e.g. a renamed field on a page). Running migrations belongs in a deploy checklist, not here.
Skip entirely: refactors with no behaviour change, test-only changes, CI/tooling, code style. If the whole diff is like that, say so — "nothing to QA manually" is a valid answer.
3. Write the checklist
Output a single markdown checklist. Rules:
- Plain English, imperative steps — "Open a feedback item and click the 👍 reaction", not "Verify ReactionController@store persists the reaction". Never reference class names, routes-as-code, or files.
- Each step pairs an action with the expected result: do X — you should see Y.
- Order steps as a walkthrough, so a person can do them top to bottom in one session without backtracking (set up state first, then exercise it, then check side effects).
- Note required preconditions up front in one line if any exist: a second test account, a feature flag enabled, an existing record to act on.
- Keep it to roughly 5–10 checkboxes. One step per behaviour, not per code path.
Format:
## QA checklist — <one-line summary of the change>
**Before you start:** <preconditions, or omit this line>
- [ ] <action> — <expected result>
- [ ] ...
End with nothing else — no summary of the diff, no code commentary.