verification-before-completion

# Verification Before Completion **Iron Law:** "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE" ## When to Use This skill applies whenever you: - Mark a todo item as complete - Claim a bug is fixed - Report a feature is ready - State implementation is done - Close a task or issue - Prepare to commit changes ## Red Flags (Violation Indicators) - [ ] "should be done" / "should work now" (assumed completion) - [ ] "probably works" / "likely fixed" (uncertainty without verification) - [ ] "seems to work" / "appears correct" (observation without test) - [ ] "Great!" / "Perfect!" / "All set!" (celebration without evidence) - [ ] "I already tested this earlier" (stale evidence) - [ ] Completion claim without test output shown - [ ] Completion claim without grep verification for file changes - [ ] Completion claim without screenshot for UI changes - [ ] Completion claim without git diff for code changes - [ ] Completion claim without build logs for configuration changes - [ ] Completion claim without CI link for deployment changes - [ ] "Just a small change, no need to verify" (size-based rationalization) ## Key Concepts ### Fresh Verification Principle Verification must be **fresh** (performed after the claimed change) and **explicit** (evidence shown, not described). **Wrong:** ``` Fixed the login bug in auth.ts. Should be working now. ``` **Correct:** ``` Fixed the login bug in auth.ts line 42: git diff src/auth.ts: - if (user.token == null) { + if (user.token === undefined || user.token === null) { Test output: ✓ should reject undefined token (15ms) ✓ should reject null token (12ms) ✓ should accept valid token (8ms) ``` ### Evidence Types by Change Type | Change Type | Required Evidence | Tool/Method | |-------------|-------------------|-------------| | Logic/algorithm | Test output showing pass | `bun test`, `pytest`, `go test` | | File creation | Grep verification or ls output | `grep -r "pattern" .` or `ls -la path/` | | UI/styling | Screenshot or video | Browser DevTools screenshot | | Configuration | Build logs showing success | `npm run build`, `cargo build` | | Deployment | CI link or deployment logs | GitHub Actions URL, kubectl logs | | API changes | API test output or curl result | `curl -X POST ...` | | Data migration | Row count or sample query | `SELECT COUNT(*) FROM ...` | | Performance fix | Benchmark comparison (before/after) | `hyperfine`, `go test -bench` | ## Enforcement Mechanism ### Tasks Integration When marking a todo as `completed`: 1. **BEFORE** changing status to `completed`, gather fresh evidence 2. **IN THE SAME MESSAGE** that marks it complete, show the evidence 3. **NEVER** mark complete in one message, then show evidence later **Violation Pattern:** ``` Message 1: "Fixed the validator. Marking todo complete." Message 2: "Here's the test output..." ``` **Correct Pattern:** ``` Message 1: "Fixed the validator. Test output: ✓ should validate email (5ms) ✓ should reject invalid format (3ms) Marking todo complete." ``` ### Rationalization Detection Common rationalizations and their counters: | Rationalization | Counter | |-----------------|---------| | "It's a trivial change" | Trivial = fast to verify, not skip | | "I tested this before" | Code changed since then, verify again | | "Same pattern as working code" | Different context = different bugs | | "Just fixing a typo" | Typos can break builds, verify | | "Only changed comments" | Comments can break doc generation | | "Can't test without production data" | Use test fixtures or staging environment | ## Examples ### Example 1: React Component Fix (TypeScript) **Scenario:** Fixed useState initialization bug **Wrong Completion:** ``` Fixed the counter initialization bug. Should be good now! ``` **Correct Completion:** ``` Fixed the counter initialization bug in Counter.tsx line 8: git diff: - const [count, setCount] = useState(); + const [count, setCount] = useState<number>(0); Test output: PASS src/Counter.test.tsx Counter component ✓ renders with initial value 0 (23ms) ✓ increments on button click (15ms) Build check: ✓ Type checking passed (1.2s) ✓ No lint errors ``` ### Example 2: Python API Endpoint (FastAPI) **Scenario:** Fixed validation error in POST /users **Wrong Completion:** ``` Added email validation to the users endpoint. Tested locally, works fine. ``` **Correct Completion:** ``` Added email validation to the users endpoint in api/users.py line 45: git diff: @app.post("/users") def create_user(user: UserCreate): + if not re.match(r"[^@]+@[^@]+\.[^@]+", user.email): + raise HTTPException(400, "Invalid email format") return db.create_user(user) Test output: test_create_user.py::test_valid_email PASSED test_create_user.py::test_invalid_email_rejected PASSED test_create_user.py::test_missing_at_sign PASSED Manual curl test: $ curl -X POST http://localhost:8000/users -d '{"email":"invalid"}' {"detail":"Invalid email format"} ``` ### Example 3: Go Configuration Change **Scenario:** Updated Docker build configuration **Wrong Completion:** ``` Updated the Dockerfile to use Go 1.22. Build should work now. ``` **Correct Completion:** ``` Updated the Dockerfile to use Go 1.22: git diff: -FROM golang:1.21-alpine +FROM golang:1.22-alpine Build verification: $ docker build -t myapp:test . [+] Building 45.3s (12/12) FINISHED => [internal] load build definition from Dockerfile => => transferring dockerfile: 234B => [1/6] FROM golang:1.22-alpine => [2/6] WORKDIR /app => [3/6] COPY go.mod go.sum ./ => [4/6] RUN go mod download => [5/6] COPY . . => [6/6] RUN go build -o /app/server => exporting to image => => writing image sha256:abc123... Run verification: $ docker run myapp:test --version v1.0.0 (go1.22.0) ``` ## Integration with Other Skills - **test-driven-development:** TDD provides the tests you'll use as verification evidence - **systematic-debugging:** Debug process ends with fix verification (this skill) - **agent-coordination-discipline:** Agents must return verification evidence, not just claims - **quality-gates:** Quality gate checks are verification evidence types ## Quick Reference **Before marking ANY task complete:** 1. ✅ Run relevant tests → capture output 2. ✅ Check file changes → show git diff or grep 3. ✅ Verify build → show build logs 4. ✅ For UI changes → take screenshot 5. ✅ For deployments → link CI run 6. ✅ Show evidence in completion message 7. ✅ Only then mark todo as completed **Remember:** If you can't show fresh evidence, the task isn't complete yet.