# Verification Before Completion

> Use when finishing any task. Final checklist before marking complete. Ensures nothing forgotten, all tests pass, documentation updated.

- Skill: `diegosouzapw/verification-before-completion` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/verification-before-completion`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/verification-before-completion/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing, Productivity
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/verification-before-completion

---


# Verification Before Completion

## Core Principle

Before declaring ANY work "complete" or "done", verify EVERYTHING works. This is the final gate before handoff.

## When to Use This Skill

- After completing `code-review` skill
- User asks "is it done?"
- **BEFORE EVERY COMMIT** (mandatory)
- Before creating pull request
- Before closing an issue
- Before marking a feature as complete

## The Iron Laws

### 1. NEVER DECLARE WORK COMPLETE WITHOUT FULL VERIFICATION

Reasons:
- Ensures nothing was forgotten
- Confirms everything actually works
- Validates against original requirements
- Prevents "one more thing" scenarios
- Professional quality gate

### 2. NEVER COMMIT WITHOUT VERIFICATION

**This skill is MANDATORY before ANY git commit.**

If you find yourself typing `git commit` without having completed this verification checklist, **STOP**.

❌ **FORBIDDEN:**
```bash
# Making changes
vim src/file.js
git add .
git commit -m "fix stuff"  # ← WRONG! No verification!
```

✅ **REQUIRED:**
```bash
# Making changes
vim src/file.js

# MANDATORY: Run verification-before-completion skill
# Complete ALL checklist items
# Only after FULL verification passes:

git add .
git commit -m "fix(api): handle null values in user profile"
```

**Authority**: Professional teams NEVER commit without verification. Unverified commits cause:
- 🐛 Bugs in production
- 💥 Broken builds
- 😡 Wasted team time
- 💸 Lost customer trust

### 3. FRONTEND + BACKEND = FULL TEST SUITE

**When changes affect both frontend and backend:**

MANDATORY before commit:
- ✅ Backend tests (unit + integration)
- ✅ Frontend tests (component + integration)
- ✅ E2E tests (full user flow)
- ✅ API tests (if API changed)

**Never commit if ANY test fails.**

## Verification Protocol

### Step 1: Announce Verification

**Template:**
```
I'm using the verification-before-completion skill to perform final checks before declaring this complete.
```

### Step 2: Requirements Verification

**Check against original user request:**

```
Original Request:
"[User's original request verbatim]"

Requirements Checklist:
✅ [Requirement 1] - Implemented and verified
✅ [Requirement 2] - Implemented and verified
✅ [Requirement 3] - Implemented and verified
```

**Questions to ask:**
- Did I do EVERYTHING the user asked for?
- Are there any "and also" or "oh and" requests I missed?
- Did the requirements change during discussion?
- Are there implied requirements I should have addressed?

### Step 3: Functionality Verification

**Test the complete feature end-to-end:**

```
End-to-End Testing:

Scenario 1: [Happy path]
Steps:
1. [Action 1] → ✅ Works
2. [Action 2] → ✅ Works
3. [Action 3] → ✅ Works
Result: ✅ Complete flow works

Scenario 2: [Alternative path]
Steps:
1. [Action 1] → ✅ Works
2. [Action 2] → ✅ Works
Result: ✅ Alternative flow works

Scenario 3: [Error path]
Steps:
1. [Action 1] → ✅ Appropriate error
Result: ✅ Error handling works
```

### Step 4: Test Verification

**Verify ALL tests pass:**

```
Test Verification:

Before running tests:
✅ Using database-backup skill (MANDATORY)
✅ Backup created: [filename]

Running complete test suite:
Command: ./scripts/safe-test.sh vendor/bin/paratest
Results:
- Total: [X] tests
- Passed: [X] tests
- Failed: 0 tests
- Duration: [time]
- Coverage: [X]%

✅ All tests pass

Running specific feature tests:
Command: ./scripts/safe-test.sh vendor/bin/paratest --filter=[Feature]
Results:
- Total: [Y] tests
- Passed: [Y] tests
- Failed: 0 tests

✅ Feature tests pass
```

**If ANY tests fail:**
```
❌ Tests failed - NOT ready for completion

Failed tests:
1. [Test name] - [Failure reason]
2. [Test name] - [Failure reason]

I need to fix these before declaring complete.
```

### Step 5: Integration Verification

**Verify integration with existing system:**

```
Integration Verification:

✅ No existing functionality broken
✅ API contracts maintained (backwards compatible)
✅ Database migrations applied successfully
✅ Database migrations can be rolled back
✅ No conflicts with other features
✅ Environment variables documented
✅ Dependencies up to date
```

**Run regression tests:**
```
Running full test suite to ensure nothing broke:
Command: ./scripts/safe-test.sh vendor/bin/paratest
Results: ✅ [X] tests, all passed
```

### Step 6: Documentation Verification

**Verify all documentation is complete:**

```
Documentation Checklist:

Code Documentation:
✅ PHPDoc/JSDoc comments on all public methods
✅ Complex logic has explanatory comments
✅ Type hints on all function parameters

API Documentation:
✅ OpenAPI/Swagger documentation generated
✅ All endpoints documented
✅ Request/response examples provided
✅ Authentication requirements noted
✅ Error responses documented

Project Documentation:
✅ README.md updated (if new feature/setup)
✅ CHANGELOG.md updated with changes
✅ .env.example includes new variables
✅ Migration instructions provided (if needed)
✅ Deployment notes added (if needed)

User-Facing Documentation:
✅ Usage examples provided
✅ Common use cases documented
✅ Troubleshooting section added
```

### Step 7: Code Quality Verification

**Final quality checks:**

```
Code Quality Checklist:

Security:
✅ No SQL injection vulnerabilities
✅ No XSS vulnerabilities
✅ No hardcoded secrets
✅ Authentication/authorization correct
✅ Input validation comprehensive
✅ OWASP Top 10 checked

Performance:
✅ No N+1 query problems
✅ Appropriate database indexes
✅ Efficient algorithms used
✅ Caching implemented where needed
✅ No performance regressions

Best Practices:
✅ DRY principle followed (no duplication)
✅ SOLID principles applied
✅ Consistent naming conventions
✅ Proper error handling
✅ Logging appropriate
✅ No commented-out code
✅ No debugging statements (console.log, dd(), etc.)
```

### Step 8: Git Verification

**Verify version control state:**

```
Git Status Check:

✅ All changes are committed
✅ Commit messages follow conventions
✅ Branch is up to date with base branch
✅ No merge conflicts
✅ .gitignore properly configured
✅ No sensitive files committed

Git log (last commits):
[Show last 3-5 commits with messages]
```

### Step 9: Deployment Verification

**Verify deployment readiness:**

```
Deployment Checklist:

✅ Environment variables documented
✅ Database migrations are reversible
✅ No breaking changes (or documented)
✅ Rollback plan exists
✅ Health check endpoints work
✅ CI/CD pipeline passes (if configured)

Migration Commands (if needed):
1. [Command 1]
2. [Command 2]

Rollback Commands (if needed):
1. [Command 1]
2. [Command 2]
```

### Step 10: Final Approval

**Present complete verification report:**

```
Verification Complete ✅

✅ All requirements met
✅ All tests pass ([X] tests)
✅ No regressions detected
✅ Documentation complete
✅ Code quality verified
✅ Security checked
✅ Performance validated
✅ Git state clean
✅ Deployment ready

The [feature name] is complete and ready for [deployment/merge/review].
```

**If issues found:**
```
Verification Found Issues ⚠️

Issues preventing completion:
1. [Critical issue 1]
2. [Critical issue 2]

I need to address these before declaring complete.
```

## Complete Verification Checklist

Use this comprehensive checklist:

### Requirements
- [ ] All original requirements met
- [ ] All "and also" requests addressed
- [ ] Implied requirements handled
- [ ] User expectations met

### Functionality
- [ ] Happy path works end-to-end
- [ ] Alternative paths work
- [ ] Error cases handled appropriately
- [ ] Edge cases handled
- [ ] No obvious bugs

### Testing
- [ ] All tests pass
- [ ] New tests added for new functionality
- [ ] Edge cases tested
- [ ] Error cases tested
- [ ] Integration tests pass
- [ ] No skipped tests
- [ ] Test coverage adequate (>80%)

### Integration
- [ ] No existing functionality broken
- [ ] API contracts maintained
- [ ] Database migrations work
- [ ] Migrations reversible
- [ ] No conflicts with other features

### Documentation
- [ ] Code comments complete
- [ ] API documentation generated
- [ ] README updated
- [ ] CHANGELOG updated
- [ ] .env.example updated
- [ ] Usage examples provided

### Code Quality
- [ ] Security vulnerabilities checked
- [ ] Performance optimized
- [ ] No duplication
- [ ] Consistent naming
- [ ] Proper error handling
- [ ] No debugging statements

### Version Control
- [ ] All changes committed
- [ ] Good commit messages
- [ ] Branch up to date
- [ ] No merge conflicts
- [ ] No sensitive files

### Deployment
- [ ] Environment variables documented
- [ ] Migrations reversible
- [ ] Rollback plan exists
- [ ] CI/CD passes

## Red Flags (Incomplete Work)

- ❌ "Just need to test one more thing" → Test it NOW
- ❌ "I'll document it later" → Document NOW
- ❌ Skipped tests → Fix them NOW
- ❌ "It works on my machine" → Verify in clean environment
- ❌ Uncommitted changes → Commit NOW
- ❌ "I'll fix that typo later" → Fix NOW

## Common Rationalizations to Reject

- ❌ "It's good enough" → Verify it's complete
- ❌ "The user just wants it working" → Professional quality still matters
- ❌ "I'm out of time" → Better to deliver late and complete than early and broken
- ❌ "I'll fix issues if they come up" → Fix known issues NOW
- ❌ "Documentation can wait" → Document before you forget

## Example Verifications

### Example 1: Complete Feature

```
I'm using the verification-before-completion skill for the user authentication feature.

Original Request:
"Add authentication to the API with email/password login, social OAuth, and protected routes"

Requirements Checklist:
✅ Email/password registration - Implemented
✅ Email/password login - Implemented
✅ Token-based authentication - Implemented (Sanctum)
✅ Social OAuth (Google, GitHub) - Implemented (Clerk)
✅ Protected routes - Implemented (auth:sanctum middleware)
✅ Logout functionality - Implemented

End-to-End Testing:

Scenario 1: Registration and Login
1. POST /register with email/password → ✅ Returns 201, user created
2. POST /login with credentials → ✅ Returns token
3. GET /user (protected) with token → ✅ Returns user data

Scenario 2: Social OAuth
1. GET /auth/redirect/google → ✅ Redirects to Google
2. Callback returns with user → ✅ User created/logged in
3. Token issued → ✅ Works

Scenario 3: Protected Routes
1. GET /user without token → ✅ Returns 401
2. GET /user with invalid token → ✅ Returns 401
3. GET /user with valid token → ✅ Returns 200

Scenario 4: Error Handling
1. Register with invalid email → ✅ Returns 422 with validation errors
2. Login with wrong password → ✅ Returns 401 with clear message
3. Login with non-existent email → ✅ Returns 401 with clear message

Test Verification:

Before running tests:
✅ Using database-backup skill
✅ Backup created: backups/database_2025-01-06_15-30-00.sql

Running complete test suite:
Command: ./scripts/safe-test.sh vendor/bin/paratest
Results:
- Total: 127 tests
- Passed: 127 tests
- Failed: 0 tests
- Duration: 8.2s
- Coverage: 87%

✅ All tests pass

Running authentication tests specifically:
Command: ./scripts/safe-test.sh vendor/bin/paratest --filter=Authentication
Results:
- Total: 15 tests
- Passed: 15 tests
- Failed: 0 tests

✅ Feature tests pass

Integration Verification:

✅ No existing functionality broken (regression tests passed)
✅ API contracts maintained (backwards compatible)
✅ Database migrations applied: users table, personal_access_tokens table
✅ Migrations can be rolled back: php artisan migrate:rollback
✅ No conflicts with other features
✅ Environment variables: CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY added to .env.example
✅ Dependencies: laravel/sanctum, clerk/clerk-sdk-php added

Documentation Verification:

Code Documentation:
✅ AuthController methods have comprehensive PHPDoc
✅ Complex OAuth logic has explanatory comments
✅ Type hints on all function parameters

API Documentation:
✅ OpenAPI documentation generated: /docs/api
✅ All endpoints documented:
   - POST /register
   - POST /login
   - POST /logout
   - GET /auth/redirect/{provider}
   - GET /auth/callback/{provider}
✅ Request/response examples provided for each
✅ Authentication requirements: "Bearer token required for protected routes"
✅ Error responses documented (401, 422, 500)

Project Documentation:
✅ README.md updated with authentication setup section
✅ CHANGELOG.md updated:
   - Added: Token-based authentication with Sanctum
   - Added: Social OAuth with Clerk (Google, GitHub)
   - Added: Protected route middleware
✅ .env.example includes CLERK_* variables
✅ Migration instructions in README: php artisan migrate
✅ Deployment notes: Clerk keys must be set in production

User-Facing Documentation:
✅ Usage examples in README:
   - How to register a user
   - How to login
   - How to use tokens
   - How to add social OAuth
✅ Common use cases documented
✅ Troubleshooting section added:
   - Token not working → Check Sanctum middleware
   - OAuth callback fails → Verify Clerk configuration

Code Quality Verification:

Security:
✅ Passwords hashed with bcrypt (Laravel default)
✅ SQL injection: Using Eloquent ORM (parameterized)
✅ XSS: No raw output, API returns JSON
✅ No hardcoded secrets (all in .env)
✅ Authentication: Sanctum properly configured
✅ Authorization: Middleware on protected routes
✅ Input validation: FormRequest classes with rules
✅ Rate limiting: 5 login attempts per minute per IP

Performance:
✅ No N+1 queries (eager loading used)
✅ Database indexes: index on users.email
✅ Token lookup optimized
✅ Caching: Not needed for auth (stateless tokens)
✅ No performance regressions

Best Practices:
✅ DRY: AuthController methods reuse validation logic
✅ SOLID: Single responsibility per method
✅ Naming: Clear, consistent (login, register, logout)
✅ Error handling: Try-catch for OAuth, clear error messages
✅ Logging: Failed login attempts logged
✅ No commented-out code
✅ No debugging statements (removed all dd(), var_dump())

Git Verification:

✅ All changes committed (3 commits)
✅ Commit messages:
   - "Add Laravel Sanctum token authentication"
   - "Add Clerk social OAuth integration"
   - "Add authentication tests and documentation"
✅ Branch 'feature/authentication' up to date with main
✅ No merge conflicts
✅ .gitignore includes .env (secrets not committed)
✅ No sensitive files in history

Deployment Verification:

✅ Environment variables documented in .env.example
✅ Database migrations reversible:
   - Rollback: php artisan migrate:rollback
   - Steps: 2 migrations to rollback
✅ No breaking changes (new feature, existing routes unchanged)
✅ Rollback plan:
   1. php artisan migrate:rollback --step=2
   2. composer remove laravel/sanctum clerk/clerk-sdk-php
   3. Remove routes from api.php
   4. Remove AuthController

Migration Commands:
1. php artisan migrate

Rollback Commands:
1. php artisan migrate:rollback --step=2

---

Verification Complete ✅

✅ All requirements met (email/password + social OAuth)
✅ All tests pass (127 tests, 15 auth tests)
✅ No regressions detected
✅ Documentation complete (code, API, project, user)
✅ Code quality verified (security, performance, best practices)
✅ Security checked (OWASP Top 10)
✅ Performance validated (no N+1, proper indexes)
✅ Git state clean (3 commits, good messages)
✅ Deployment ready (migrations, rollback plan)

The user authentication feature is complete and ready for deployment/merge.
```

### Example 2: Issues Found

```
I'm using the verification-before-completion skill for the activity logging feature.

Original Request:
"Track user activity in a database table including IP address and user agent"

Requirements Checklist:
✅ Activity logging database table
✅ Logs user registration
✅ Logs user login
✅ Logs user logout
✅ Captures IP address
✅ Captures user agent

End-to-End Testing:
✅ User registration creates log entry with IP and user agent
✅ User login creates log entry
✅ User logout creates log entry

Test Verification:

Before running tests:
✅ Using database-backup skill
✅ Backup created

Running tests:
❌ FAILED - 2 test failures

Failed tests:
1. ActivityLogTest::test_logging_includes_user_agent
   - Expected: User agent to be captured
   - Actual: user_agent column is NULL
   - Reason: ActivityLogger not capturing user agent correctly

2. ActivityLogTest::test_user_can_view_own_activity
   - Expected: GET /user/activity returns activity logs
   - Actual: 404 Not Found
   - Reason: Forgot to implement the viewing endpoint

Verification Found Issues ⚠️

Critical Issues (preventing completion):
1. User agent not being captured
   - Tests expect it, code doesn't capture it
   - Fix: Update ActivityLogger to use $request->userAgent()

2. Missing endpoint to view activity logs
   - User probably wants to see their activity
   - This is an implied requirement
   - Fix: Add GET /user/activity endpoint

I need to fix these issues before declaring complete.
```

**After fixing:**
```
Fixed issues:
✅ Updated ActivityLogger to capture user agent correctly
✅ Added GET /user/activity endpoint
✅ Added test for new endpoint
✅ All tests now pass (18 tests)

Re-running verification:
✅ All requirements met (including implied requirement)
✅ All tests pass
✅ End-to-end testing successful
✅ Documentation updated

Verification Complete ✅ - Activity logging is now complete and ready.
```

## Integration with Other Skills

**Before verification-before-completion**: Use `code-review` skill
**After verification-before-completion**: Ready to commit/deploy
**If issues found**: Fix and re-verify

## Authority

**This skill is based on**:
- Software engineering best practice: Quality gates
- Professional standard: Definition of "done"
- Agile methodology: Acceptance criteria
- Empirical evidence: Final verification catches 40% of remaining issues

**Social Proof**: Professional teams have explicit "definition of done" checklists. No code is "complete" without verification.

## Your Commitment

Before using this skill, confirm:
- [ ] I will NEVER declare work complete without verification
- [ ] I will CHECK every item in the verification checklist
- [ ] I will RUN all tests as part of verification
- [ ] I will FIX any issues found
- [ ] I will DOCUMENT verification results

---

**Bottom Line**: "Complete" means fully verified, tested, documented, and ready to deploy. Never declare done without proving it's done.