Manual Test Checklists

At the end of each epic, Claude gives you a checklist of things to try in the running app. This is Gate 1: your check that the epic works the way you intended before it merges into main.

When you get the checklist

You get the checklist once the epic’s automated checks pass: the full quality gates, the code review, and the end-to-end browser tests. Claude then opens a check-off page in your browser, saved at generated-docs/epics/<slug>/manual-tests.html.

Open the page in your normal web browser. The browser built into VS Code blocks copying to the clipboard, so the Done button doesn’t work there. If the page can’t be opened, Claude shows the checklist in the chat instead.

What the checklist covers

• Check these first: assumptions Claude couldn’t verify against your real backend, such as the shape of a response. Automated tests can’t catch these, because the mock data makes the same assumption as the code.
• Tests for each story: the main success path, plus edge cases such as empty states, errors and validation failures.
• Role logins: if your app has several roles, the page lists a login for each, which you can copy with one click. Tests are ordered so you switch roles as little as possible.

Stories with nothing to see in the app, such as background setup work, have no tests on the checklist.

How to sign off

1. Work through the tests in your browser and tick each one that passes.
2. Click Done. The page copies your results to the clipboard.
3. Paste the results into the chat. If everything passed, you can type all passed instead.

In the chat, you can also answer All good, Found an issue or Skip for now.

When something is wrong

Describe what you expected and what you saw. Claude works out what kind of problem it is:

Problem	What Claude does
A bug, such as a broken button or a wrong total	Fixes it
A change of mind, such as “move the filter to the right”	Fixes it and, if you built from a design, records it as your decision so a later design update doesn’t undo it
A failed “check these first” item	Asks you for the real answer, then corrects the API spec, the mock data and the tests before fixing the code

After a fix, Claude re-runs the automated checks and reopens the page. Tests that passed before stay ticked. Only the tests the fix affected come back unticked, so you re-test only what changed.

Claude allows three rounds of fixes per epic. After the third, it asks whether to merge with the remaining issues recorded in the journal, or to stop.

Skipping the manual test

Choosing Skip for now moves the epic on to the merge without a manual test. Claude records the skip in the epic’s journal. Skipping removes your only check of how the epic behaves for a real user, so use it sparingly.