verification-before-completion✓ ناجح

محتوى SKILL.md

---
name: verification-before-completion
description: "Use when claiming task completion or marking items as done. Covers completion evidence requirements, verification methods, and anti-rationalization patterns."
keywords: [completion, done, working, ready, verification, evidence, test-output, grep-verification, ci-cd, build-logs, git-diff, screenshot, should-work, probably-works, seems-to, rationalization, todo-complete]
created: 2026-01-20
updated: 2026-01-20
plugin: dev
type: discipline
difficulty: beginner
---

# 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.

الترخيص

الترخيص المُعلن: MIT

MIT License

Copyright (c) 2026 MadAppGang

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

عرض الترخيص في المستودع المصدري — النسخة المنشورة هناك هي المرجع.