claudekit/skills/verification-before-completion/SKILL.md

---
name: verification-before-completion
user-invocable: true
description: >
  Use when about to claim ANY work is complete, fixed, passing, or done. Activate whenever you are tempted to say "done", "fixed", "tests pass", "build succeeds", "deployed", or any completion claim. Also trigger before committing code, before creating PRs, before responding to the user that a task is finished, or when reviewing agent-produced work. This is mandatory -- NEVER claim completion without running verification commands and reading their output. Evidence before assertions, always.
---

# Verification Before Completion

## When to Use

- Before claiming tests pass
- Before claiming build succeeds
- Before claiming bug is fixed
- Before marking any task complete
- Before declaring success to user

## When NOT to Use

- Mid-task progress updates where you are reporting interim status, not claiming completion
- Research or exploration tasks where the output is knowledge, not code
- Design or brainstorming phases where no verifiable artifacts have been produced yet

---

## The 5-Step Verification Process

### Step 1: IDENTIFY

Determine the command that proves your assertion:

```markdown
Claim: "Tests pass"
Verification command: npm test

Claim: "Build succeeds"
Verification command: npm run build

Claim: "Linting passes"
Verification command: npm run lint
```

### Step 2: EXECUTE

Run the command fully and freshly:

```bash
# Don't rely on cached results
# Don't assume previous run is still valid
npm test
```

### Step 3: READ

Read the complete output and exit codes:

```bash
# Check output carefully
# Don't skim - read every line
# Note exit code (0 = success)
```

### Step 4: VERIFY

Confirm the output matches your claim:

```markdown
Claim: "All tests pass"
Output shows: "42 passing, 0 failing"
Verification: ✓ Claim is accurate
```

### Step 5: CLAIM

Only now make the claim, with evidence:

```markdown
✓ All tests pass (42 passing, verified at 2024-01-15 14:30)
```

---

## Required Validations by Category

### Testing

```bash
# Run test command
npm test

# Verify in output:
# - Zero failures
# - Expected test count
# - No skipped tests (unless intentional)
```

**Not valid**: "Tests should pass" without running them

### Linting

```bash
# Run linter completely
npm run lint

# Verify in output:
# - Zero errors
# - Zero warnings (or acceptable known warnings)
```

**Not valid**: Using lint as proxy for build success

### Building

```bash
# Run build command
npm run build

# Verify:
# - Exit code 0
# - Build artifacts created
# - No errors in output
```

**Not valid**: Assuming lint passing means build passes

### Bug Fixes

```bash
# Step 1: Reproduce original bug
npm test -- --grep "failing test"
# Should fail

# Step 2: Apply fix

# Step 3: Verify fix works
npm test -- --grep "failing test"
# Should pass
```

**Not valid**: Claiming fix works without reproducing original failure

### Regression Tests

Complete red-green cycle required:

```bash
# 1. Write test, run it
npm test  # Should PASS with new test

# 2. Revert the fix
git stash

# 3. Run test again
npm test  # Should FAIL (proves test catches the bug)

# 4. Restore fix
git stash pop

# 5. Run test again
npm test  # Should PASS
```

### Requirements Verification

```markdown
## Original Requirements
1. User can login with email
2. User can reset password
3. Session expires after 24 hours

## Verification Checklist
- [x] Requirement 1: Tested login flow manually + unit tests
- [x] Requirement 2: Tested reset flow manually + integration test
- [x] Requirement 3: Verified SESSION_TIMEOUT=86400 in config + test
```

### Agent Work Verification

Don't trust agent reports blindly:

```bash
# Agent claims: "Fixed the bug in user.ts"

# Verify independently:
git diff src/user.ts  # Check actual changes
npm test              # Verify tests pass
```

---

## Forbidden Language

Never use these phrases without verification:

| Forbidden | Why |
|-----------|-----|
| "should work" | Implies uncertainty |
| "probably fixed" | Not verified |
| "seems to pass" | Didn't read output |
| "I think it's done" | Guessing |
| "Great!" (before checking) | Premature celebration |
| "Done!" (before verification) | Unverified claim |

### Replace With

| Instead Say | After |
|-------------|-------|
| "Tests pass" | Running tests, seeing 0 failures |
| "Build succeeds" | Running build, exit code 0 |
| "Bug is fixed" | Reproducing bug, verifying fix |

---

## Anti-Patterns

### Partial Verification

```markdown
BAD: "I ran one test and it passed"
GOOD: "Full test suite passes (42/42)"
```

### Relying on Prior Runs

```markdown
BAD: "Tests passed earlier"
GOOD: "Tests pass now (just ran)"
```

### Skipping Verification

```markdown
BAD: "This is a small change, no need to verify"
GOOD: "Small change, but verified: tests pass, lint clean"
```

### Trusting Without Checking

```markdown
BAD: Agent said it's fixed, so it's fixed
GOOD: Agent said it's fixed, I verified by running tests
```

---

## Verification Checklist Template

Use before claiming completion:

```markdown
## Task: [Task Name]

### Verification Steps
- [ ] Tests run: `npm test`
  - Result: [X passing, Y failing]
- [ ] Lint passes: `npm run lint`
  - Result: [No errors]
- [ ] Build succeeds: `npm run build`
  - Result: [Exit code 0]
- [ ] Requirements met:
  - [ ] Requirement 1: [How verified]
  - [ ] Requirement 2: [How verified]

### Evidence
[Paste relevant output or screenshots]

### Conclusion
✓ Task complete, all verifications passed
```

---

## Stack-Specific Verification Commands

### Python/FastAPI

```bash
pytest -v --cov=src --cov-report=term-missing   # Tests + coverage
ruff check .                                      # Linting
mypy src/ --strict                                # Type checking
# All-in-one
pytest -v && ruff check . && mypy src/
```

### TypeScript/NestJS

```bash
npm test                    # Tests
npm run lint                # Linting
npx tsc --noEmit            # Type checking
npm run build               # Build (catches import issues)
# All-in-one
npm test && npm run lint && npm run build
```

### Next.js

```bash
npm test                    # Tests
next lint                   # Linting
npx tsc --noEmit            # Type checking
next build                  # Build (catches SSR + RSC issues)
# All-in-one
npm test && next lint && next build
```

### React (Vite)

```bash
npx vitest run              # Tests
npm run lint                # Linting
npx tsc --noEmit            # Type checking
npm run build               # Build
# All-in-one
npx vitest run && npm run lint && npm run build
```

### Verification Evidence Template

When claiming completion, paste evidence in this format:

```markdown
**Verification Evidence:**
- Tests: `pytest -v` → 47 passed, 0 failed
- Lint: `ruff check .` → no issues
- Types: `mypy src/` → Success: no issues found
```

```markdown
**Verification Evidence:**
- Tests: `npm test` → 23 passed, 0 failed
- Lint: `npm run lint` → no warnings
- Build: `npm run build` → compiled successfully
```

---

## Related Skills

- `test-driven-development` -- TDD naturally produces verifiable work; verification confirms the TDD cycle was followed correctly
- `systematic-debugging` -- After debugging, verification ensures the fix actually resolves the issue
- `requesting-code-review` -- Verification should happen before requesting review to avoid wasting reviewer time on broken code