Verify commands
A verify command is an acceptance test. Before shipping one, answer: if this command were silently doing nothing, what in its output would tell me? If you cannot answer, you have a command, not a check. Fix the command; do not invent a statement for it.
Name the failing direction
Next to every runnable check, write one line naming the observable signal that means failure: non-zero exit, "0 passed" in the summary line, the coverage line is absent, stderr contains "ECONNREFUSED". "The command fails" and "an error occurs" are restatements, not signals. TBD, N/A, and none are refusals. Short is fine; non-zero exit is complete. Prefer the signal the tool actually emits over one you imagine: for a command that already ran, state what you saw; for a new one, take the signal from the tool's documented output. N commands need N statements.
Ground every path
Inherit the command that already worked in this repo, verbatim, before deriving a new one. A cd target or --prefix target must exist, or be created by an earlier step, and must hold the matching manifest (package.json, Makefile, pyproject.toml). Prefer npm --prefix <dir> run <script> over cd <dir> && npm run <script>; it does not depend on the caller's working directory. Do not hand-reason the filesystem: list it. If you cannot ground a path, say so instead of guessing.
Shapes that pass while measuring nothing
| Trap | Why it passes | Instead |
|---|---|---|
pnpm ls vite | grep -E '^vite@7' |
tree output starts each line with └──, so ^ never matches |
drop the anchor, or match (└|├)── vite@7 |
npm test | grep '714 passed' |
a count recalled from memory, stale from training | grep -E '[0-9]+ passed', or run the count first |
X=$(cmd 2>/dev/null || echo 0) feeding [ "$X" = "$Y" ] |
both sides default to 0 when inputs are missing, so parity passes on nothing |
let the failure propagate, or guard with test -f and exit |
grep -c 'LITERAL' file == 0 while an instruction or comment quotes LITERAL |
the gate trips on comment text, not on code | describe the forbidden thing by concept, not by literal |
! grep -q PATTERN file when a sibling change legitimately adds PATTERN elsewhere in the file |
a file-wide negative is unsatisfiable across regions | scope it: awk '/^def f/,/^def /' file | grep, or an AST check, or a unit test |
| a test-name filter that matches zero tests | exit 0 with nothing asserted | list tests first (--collect-only, --list), then run the one named test |
npm test | tail -20 whose exit status is read as the verdict |
a pipeline exits with its last command's status, so tail reports 0 while npm test failed |
start the same command line with set -o pipefail; npm test | tail -20 (bash, zsh). A set from an earlier tool call is gone |
The anchor trap has a family: npm ls, yarn list, docker ps, and kubectl get all print column or tree prefixes. || echo default is acceptable only when absence is the default and the value is not used in a comparison meant to detect absence.
Reviewing someone else's command
Report; never prescribe a replacement path you did not verify. A prescribed path is copied verbatim and carries zero information. A missing directory or manifest is a blocker: quote the raw target. A dynamic path, glob, ~, or variable is a warning, not a licence to guess the literal.