verifying

Files (1)

• SKILL.md

SKILL.md (first lines)

# Verifying Before Declaring Done

## Pre-Flight Checklist

Run these sequentially before any completion claim. Stop at the first failure.

- [ ] Tests pass — run the full suite, read the output, confirm zero failures
- [ ] Linter/formatter clean — run the project linter, confirm zero errors
- [ ] Build succeeds — run the build command, confirm exit code 0
- [ ] Requirements satisfied — re-read the plan line by line, check each item off
- [ ] No stale markers — search for TODO/FIXME/HACK that should have been resolved
- [ ] Edge cases covered — confirm spec-defined edge cases have corresponding tests
- [ ] No regressions — existing functionality still works
- [ ] Git status clean — no untracked files that belong in the commit

## The Verification Gate

Before stating any positive claim about work status:

1. **Identify** the command that proves the claim.
2. **Execute** it in full. Not a partial run. Not a cached result.
3. **Read** the complete output. Check exit codes. Count failures.
4. **Confirm** the output supports the claim.
   - Supported: state claim with evidence.
   - Not supported: state actual status with evidence.
5. **Only then** make the claim.

Skipping any step converts a verification into a guess.

## Claims and Their Proof

| Claim | Required evidence | Insufficient |
|-------|-------------------|--------------|
| Tests pass | Test runner output showing 0 failures | Prior run, "should pass" |
| Linter clean | Linter output showing 0 errors | Partial run, assumption |
| Build succeeds | Build command exiting 0 | Linter passing |
| Bug resolved | Reproducer test now passes | Code changed |
| Regression covered | Red-green cycle confirmed | Single green run |
| Agent task complete | VCS diff reviewed | Agent self-report |
| Requirements met | Line-by-line plan check | "Tests pass" |

## Deflecting Rationalizations

| Rationalization | Counter |
|-----------------|---------|
| "Should work now" | Run it. |
| "High confidence" | Confidence is not output. |
| "Just this once" | No carve-outs. |
| "Linter passed so build is fine" | Different tools check different things. |
| "Agent reported success" | Verify independently. |
| "Partial check covers it" | Partial proof is no proof. |

## Halt Signals

Stop and verify if any of these surface:

- Words like "should", "probably", "seems to" near a status claim
- Positive framing ("Done", "Fixed", "All good") without a preceding command run
- About to commit, push, or open a PR
- Relying on an agent's self-reported result
- Wanting the task to be over

## Gotchas

- **Stale evidence** — Output from a previous message or earlier in the same message does not count. Verification must be fresh, run after the final change.
- **Linter-build conflation** — Passing the linter does not prove the build compiles. Passing the build does not prove tests pass. Each layer requires its own check.
- **Agent trust** — Subagents report success optimistically. Always inspect the actual diff and run verification independently.
- **Partial suite runs** — Running one test file instead of the full suite misses regressions. Run the full suite unless the project explicitly supports scoped verification.
- **Satisfaction bias** — The urge to say "done" intensifies as effort increases. The more time invested, the more scrutiny the final claim deserves.
- **Implicit claims** — Phrases like "that should handle it" or "looks correct" are completion claims. They require the same evidence as explicit ones.

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn