verification-before-completion

Verification Before Completion

The Law

YOU CANNOT CLAIM SUCCESS WITHOUT EVIDENCE.
"It should work" is not evidence.
"I believe it works" is not evidence.
Running the command and reading the output IS evidence.

When to Use

Use this skill before saying ANY of these:

• "Done" / "Complete" / "Finished"
• "The tests pass"
• "The build succeeds"
• "The feature works"
• "The bug is fixed"

If you have not run the verification command and read its output in this session, you cannot make the claim.

The Verification Process

Step 1: Identify the Verification Command

Before claiming completion, state the exact command that proves the claim:

Claim	Verification Command
"Tests pass"	npm test / pytest / go test ./... / cargo test
"Build succeeds"	npm run build / go build ./... / cargo build --release
"Type checking passes"	npx tsc --noEmit / mypy .
"Bug is fixed"	Run the exact steps that reproduced the bug
"Feature works"	Run the specific user flow end-to-end
"Coverage is 80%+"	npm run test:coverage / pytest --cov
"No security issues"	npm audit / cargo audit / bandit -r .

Step 2: Run the Command Fresh

Run it NOW, in this session. Not "I ran it earlier." Not "it was passing before I made changes."

Fresh means: After the last code change, run the command again.

Step 3: Read the Actual Output

Do not skim. Do not assume. Read:

• The exit code (0 = success)
• The test count (N passing, 0 failing)
• The exact error messages if any

Step 4: Confirm the Output Matches the Claim

Only if the output actually confirms the claim, state completion.

If the output contradicts the claim → fix the issue, then re-verify from Step 2.

Step 5: Prune Workspace Artifacts (Mandatory)

After verification succeeds, before reporting done, clean up all diagnostic debris produced during this task:

# Delete temporary logs and stack traces generated in this session
rm -f *.log *.tmp build-output.txt error-dump.txt
rm -f *-stack-trace.txt *-stderr.txt *-debug.txt
# Truncate test output files that were created locally (keep test results, not raw stdout dumps)

What to clean:

• Stack traces saved to local files (*.log, *-error.txt, *-trace.txt)
• Build output dumps that were written to the workspace during debugging
• Temporary debugging files created to capture stdout/stderr
• Any file whose sole purpose was to hold error output during this session

What NOT to clean:

• Source files, test files, configuration files
• Official test result files (JUnit XML, coverage reports) that the project intentionally persists
• Any file tracked by git (git ls-files — don't delete those)

Why this matters: Stack traces and log dumps left in the workspace are silently read by Claude Code in subsequent iterations, inflating context with noise that was only relevant during the error state. Pruning keeps the next agent's context focused.

Rationalization Red Flags

These thoughts mean you have NOT verified — stop and verify:

• "The tests were passing before I made this change"
• "This is a small change, it definitely didn't break anything"
• "I can see from the code that it's correct"
• "The logic looks right"
• "It should work based on how the library works"
• "I'll verify after I report back"
• "The previous run passed so it's fine"

Every one of these is a lie told to avoid the discomfort of possibly seeing a failure. Run the command. Read the output. Then report.

Completion Statement Format

When you have verified, state completion like this:

Verification run: `npm test`
Output:
  ✓ 42 tests passing
  0 failing
  Coverage: 84%

Task complete. ✓

Never omit the verification output. It is the proof.

Why This Matters

LLMs are optimistic by default. They report what should be true, not what is true. A test suite that "should pass" fails 30% of the time after non-trivial changes. The only way to know is to run it.

One unverified claim compounds into three broken downstream tasks. Five minutes of verification saves two hours of debugging later.