write-manual-verification-plan

Write Manual Verification Plan

A by-hand checklist is a record, not a message: every step says what to do and what you should see, and the checklist outlives the session that wrote it.

When to Use

Some checks can only be made by a person in front of an environment: a DAW loading a plugin, a simulator running an app, a browser rendering a page, a physical device, a printer. The list of those checks gets asked for, produced, and then fails in three ways. It does not say what success looks like, so the person running it cannot tell a pass from a fail. It does not separate "nothing happened, as intended" from "nothing was running". And it lives in scrollback, so it is rebuilt from scratch every time someone asks for it again, losing every result already reported against it.

Use this skill when:

• Someone asks what can be verified manually, what host or device verification needs, or to be walked through what to test.
• A plan or phase gate has an acceptance criterion that only a real environment can show.
• Someone asks to list or reprint the verification steps. The checklist already exists somewhere, and the job is to find it.
• Results come back as free text against step numbers.
• Someone says they are not sure what a step is looking for. That step's Expected has failed its reader, and the fix belongs in the record.

Do not prescribe a manual run for a check whose quantity has no component only the environment has. That check belongs in an automated test, however important it is. Keep a deferred row linked to its automation issue until that coverage exists; once covered, retire the row with a reference to the test. And do not use this skill to judge whether an automated instrument can fail: that is the plant-defects skill, which is the same discipline pointed at automated checks.

Core Principles

1. Expected is an observation a person can check without having written the code. Name where the observation appears (the output line, the pixel, the column, the field), the value, the tolerance in the units the reader sees, and what each plausible wrong reading means. "The trace should be visible" is not an Expected. "The implies sample value on the highest peak line reads +1.0889, within ±0.002" is.
2. A null result has three readings. Nothing happened because the change works, because the instrument was not running, or because the conditions could not expose the defect. Every step whose success is an absence carries evidence that separates the intended result from both invalid cases in the same run.
3. Nothing is worth concluding before the build is confirmed. An environment runs what is installed, not what was just built. Step 0 confirms the build under test at the start of every session. A result recorded before that confirmation stays pending; keep it only if Step 0 confirms the same build and nothing was installed in between, otherwise mark it void.
4. The record outlives the session. Persist the checklist to the plan or the issue before presenting it, update that one record in place, and reprint from it. A checklist rebuilt from memory loses every result already recorded against it.
5. Record readings, not ticks. Where Expected is a measurement, the measured value goes into the record with its date, build, and environment. Later corrections get checked against those figures, and a tick gives them nothing to check against.
6. Put the step where the quantity lives. A step is by hand in principle only when what it checks passes through something only the environment has. Where it merely has not been automated yet, it is a deferral, and it links the issue that will automate it.
7. Scope before splitting. State up front which steps need an exclusive resource, so a long checklist can be split across sessions without invalidating itself.